@wakastellar/ui 2.0.0 → 2.1.1

package/src/components/waka-checkout-stepper/index.tsx

@@ -0,0 +1,976 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils/cn"
+import {
+  Check,
+  ShoppingCart,
+  Truck,
+  CreditCard,
+  ClipboardCheck,
+  PartyPopper,
+  ChevronLeft,
+  ChevronRight,
+  SkipForward,
+  AlertCircle,
+  Loader2,
+  LucideIcon,
+} from "lucide-react"
+
+// ============================================
+// TYPES
+// ============================================
+
+export type CheckoutStepId = "cart" | "shipping" | "payment" | "review" | "confirmation"
+
+export type CheckoutStepStatus = "pending" | "current" | "completed" | "error" | "skipped"
+
+export interface CheckoutStepValidation {
+  /** Whether the step is valid */
+  isValid: boolean
+  /** Error message if invalid */
+  errorMessage?: string
+  /** Field-level errors */
+  fieldErrors?: Record<string, string>
+}
+
+export interface CheckoutStep {
+  /** Unique step identifier */
+  id: CheckoutStepId | string
+  /** Step title */
+  title: string
+  /** Step description */
+  description?: string
+  /** Custom icon (optional) */
+  icon?: LucideIcon
+  /** Step content component */
+  content?: React.ReactNode
+  /** Whether step is optional (can be skipped) */
+  optional?: boolean
+  /** Whether step is disabled */
+  disabled?: boolean
+  /** Validation function for the step */
+  validate?: () => CheckoutStepValidation | Promise<CheckoutStepValidation>
+  /** Summary data for the sidebar */
+  summary?: React.ReactNode
+}
+
+export interface CheckoutStepperProps {
+  /** List of checkout steps */
+  steps: CheckoutStep[]
+  /** Current step index (0-indexed) */
+  currentStep?: number
+  /** Callback when step changes */
+  onStepChange?: (stepIndex: number, stepId: string) => void
+  /** Callback when checkout is completed */
+  onComplete?: () => void
+  /** Layout orientation */
+  orientation?: "horizontal" | "vertical"
+  /** Size variant */
+  size?: "sm" | "md" | "lg"
+  /** Allow clicking on steps to navigate */
+  clickable?: boolean
+  /** Only allow navigation to previous steps */
+  allowPreviousOnly?: boolean
+  /** Show step content */
+  showContent?: boolean
+  /** Show summary sidebar */
+  showSummary?: boolean
+  /** Summary sidebar position */
+  summaryPosition?: "left" | "right"
+  /** Enable animated transitions */
+  animated?: boolean
+  /** Animation direction */
+  animationDirection?: "slide" | "fade" | "scale"
+  /** Loading state */
+  isLoading?: boolean
+  /** Custom class name */
+  className?: string
+  /** Navigation labels */
+  labels?: {
+    back?: string
+    next?: string
+    skip?: string
+    complete?: string
+    processing?: string
+  }
+}
+
+export interface UseCheckoutStepperOptions {
+  /** Initial step index */
+  initialStep?: number
+  /** List of steps */
+  steps: CheckoutStep[]
+  /** Callback when step changes */
+  onStepChange?: (stepIndex: number, stepId: string) => void
+  /** Callback when checkout completes */
+  onComplete?: () => void
+  /** Validate before proceeding */
+  validateOnNext?: boolean
+}
+
+export interface UseCheckoutStepperReturn {
+  /** Current step index */
+  currentStep: number
+  /** Current step data */
+  currentStepData: CheckoutStep | undefined
+  /** All steps with status */
+  stepsWithStatus: (CheckoutStep & { status: CheckoutStepStatus })[]
+  /** Total number of steps */
+  totalSteps: number
+  /** Whether on first step */
+  isFirstStep: boolean
+  /** Whether on last step */
+  isLastStep: boolean
+  /** Whether checkout is complete */
+  isComplete: boolean
+  /** Whether currently validating */
+  isValidating: boolean
+  /** Current validation error */
+  validationError: string | null
+  /** Go to specific step */
+  goToStep: (index: number) => Promise<boolean>
+  /** Go to next step */
+  nextStep: () => Promise<boolean>
+  /** Go to previous step */
+  prevStep: () => void
+  /** Skip current step (if optional) */
+  skipStep: () => void
+  /** Complete checkout */
+  completeCheckout: () => Promise<boolean>
+  /** Reset stepper */
+  reset: () => void
+  /** Get step status */
+  getStepStatus: (index: number) => CheckoutStepStatus
+  /** Skipped steps */
+  skippedSteps: Set<number>
+  /** Mark step as completed manually */
+  markStepCompleted: (index: number) => void
+}
+
+export interface CheckoutStepperContextValue extends UseCheckoutStepperReturn {
+  orientation: "horizontal" | "vertical"
+  size: "sm" | "md" | "lg"
+  clickable: boolean
+  allowPreviousOnly: boolean
+  animated: boolean
+  animationDirection: "slide" | "fade" | "scale"
+  isLoading: boolean
+}
+
+// ============================================
+// DEFAULT STEPS
+// ============================================
+
+const defaultStepIcons: Record<CheckoutStepId, LucideIcon> = {
+  cart: ShoppingCart,
+  shipping: Truck,
+  payment: CreditCard,
+  review: ClipboardCheck,
+  confirmation: PartyPopper,
+}
+
+// ============================================
+// HOOK: useCheckoutStepper
+// ============================================
+
+export function useCheckoutStepper({
+  initialStep = 0,
+  steps,
+  onStepChange,
+  onComplete,
+  validateOnNext = true,
+}: UseCheckoutStepperOptions): UseCheckoutStepperReturn {
+  const [currentStep, setCurrentStep] = React.useState(initialStep)
+  const [completedSteps, setCompletedSteps] = React.useState<Set<number>>(new Set())
+  const [skippedSteps, setSkippedSteps] = React.useState<Set<number>>(new Set())
+  const [isComplete, setIsComplete] = React.useState(false)
+  const [isValidating, setIsValidating] = React.useState(false)
+  const [validationError, setValidationError] = React.useState<string | null>(null)
+
+  const totalSteps = steps.length
+  const isFirstStep = currentStep === 0
+  const isLastStep = currentStep === totalSteps - 1
+  const currentStepData = steps[currentStep]
+
+  const getStepStatus = React.useCallback(
+    (index: number): CheckoutStepStatus => {
+      if (skippedSteps.has(index)) return "skipped"
+      if (completedSteps.has(index)) return "completed"
+      if (index === currentStep) return "current"
+      if (index < currentStep) return "completed"
+      return "pending"
+    },
+    [currentStep, completedSteps, skippedSteps]
+  )
+
+  const stepsWithStatus = React.useMemo(
+    () =>
+      steps.map((step, index) => ({
+        ...step,
+        status: getStepStatus(index),
+      })),
+    [steps, getStepStatus]
+  )
+
+  const validateCurrentStep = React.useCallback(async (): Promise<boolean> => {
+    const step = steps[currentStep]
+    if (!step?.validate) return true
+
+    setIsValidating(true)
+    setValidationError(null)
+
+    try {
+      const result = await step.validate()
+      if (!result.isValid) {
+        setValidationError(result.errorMessage || "Validation failed")
+        return false
+      }
+      return true
+    } catch (error) {
+      setValidationError("An error occurred during validation")
+      return false
+    } finally {
+      setIsValidating(false)
+    }
+  }, [currentStep, steps])
+
+  const goToStep = React.useCallback(
+    async (index: number): Promise<boolean> => {
+      if (index < 0 || index >= totalSteps) return false
+      if (steps[index]?.disabled) return false
+
+      // If going forward, validate current step
+      if (index > currentStep && validateOnNext) {
+        const isValid = await validateCurrentStep()
+        if (!isValid) return false
+      }
+
+      // Mark current step as completed if moving forward
+      if (index > currentStep) {
+        setCompletedSteps((prev) => new Set(prev).add(currentStep))
+      }
+
+      setCurrentStep(index)
+      setValidationError(null)
+      onStepChange?.(index, steps[index].id)
+      return true
+    },
+    [currentStep, totalSteps, steps, validateOnNext, validateCurrentStep, onStepChange]
+  )
+
+  const nextStep = React.useCallback(async (): Promise<boolean> => {
+    if (isLastStep) return false
+    return goToStep(currentStep + 1)
+  }, [isLastStep, currentStep, goToStep])
+
+  const prevStep = React.useCallback(() => {
+    if (isFirstStep) return
+    setCurrentStep((prev) => prev - 1)
+    setValidationError(null)
+    onStepChange?.(currentStep - 1, steps[currentStep - 1].id)
+  }, [isFirstStep, currentStep, steps, onStepChange])
+
+  const skipStep = React.useCallback(() => {
+    const step = steps[currentStep]
+    if (!step?.optional || isLastStep) return
+
+    setSkippedSteps((prev) => new Set(prev).add(currentStep))
+    setCurrentStep((prev) => prev + 1)
+    setValidationError(null)
+    onStepChange?.(currentStep + 1, steps[currentStep + 1].id)
+  }, [currentStep, steps, isLastStep, onStepChange])
+
+  const completeCheckout = React.useCallback(async (): Promise<boolean> => {
+    if (validateOnNext) {
+      const isValid = await validateCurrentStep()
+      if (!isValid) return false
+    }
+
+    setCompletedSteps((prev) => new Set(prev).add(currentStep))
+    setIsComplete(true)
+    onComplete?.()
+    return true
+  }, [currentStep, validateOnNext, validateCurrentStep, onComplete])
+
+  const reset = React.useCallback(() => {
+    setCurrentStep(initialStep)
+    setCompletedSteps(new Set())
+    setSkippedSteps(new Set())
+    setIsComplete(false)
+    setIsValidating(false)
+    setValidationError(null)
+  }, [initialStep])
+
+  const markStepCompleted = React.useCallback((index: number) => {
+    setCompletedSteps((prev) => new Set(prev).add(index))
+  }, [])
+
+  return {
+    currentStep,
+    currentStepData,
+    stepsWithStatus,
+    totalSteps,
+    isFirstStep,
+    isLastStep,
+    isComplete,
+    isValidating,
+    validationError,
+    goToStep,
+    nextStep,
+    prevStep,
+    skipStep,
+    completeCheckout,
+    reset,
+    getStepStatus,
+    skippedSteps,
+    markStepCompleted,
+  }
+}
+
+// ============================================
+// CONTEXT
+// ============================================
+
+const CheckoutStepperContext = React.createContext<CheckoutStepperContextValue | null>(null)
+
+export function useCheckoutStepperContext() {
+  const context = React.useContext(CheckoutStepperContext)
+  if (!context) {
+    throw new Error("useCheckoutStepperContext must be used within a WakaCheckoutStepper")
+  }
+  return context
+}
+
+// ============================================
+// SUB-COMPONENTS
+// ============================================
+
+interface StepIndicatorProps {
+  step: CheckoutStep & { status: CheckoutStepStatus }
+  index: number
+}
+
+function StepIndicator({ step, index }: StepIndicatorProps) {
+  const { size, animated } = useCheckoutStepperContext()
+
+  const sizeClasses = {
+    sm: "h-8 w-8 text-xs",
+    md: "h-10 w-10 text-sm",
+    lg: "h-12 w-12 text-base",
+  }
+
+  const iconSizes = {
+    sm: "h-4 w-4",
+    md: "h-5 w-5",
+    lg: "h-6 w-6",
+  }
+
+  const statusClasses = {
+    pending: "bg-muted text-muted-foreground border-2 border-muted-foreground/30",
+    current: "bg-primary text-primary-foreground border-2 border-primary shadow-lg shadow-primary/25",
+    completed: "bg-green-500 text-white border-2 border-green-500",
+    error: "bg-destructive text-destructive-foreground border-2 border-destructive",
+    skipped: "bg-muted text-muted-foreground border-2 border-dashed border-muted-foreground/50",
+  }
+
+  const Icon = step.icon || defaultStepIcons[step.id as CheckoutStepId]
+
+  const renderContent = () => {
+    if (step.status === "completed") {
+      return <Check className={iconSizes[size]} />
+    }
+
+    if (step.status === "error") {
+      return <AlertCircle className={iconSizes[size]} />
+    }
+
+    if (step.status === "skipped") {
+      return <SkipForward className={iconSizes[size]} />
+    }
+
+    if (Icon) {
+      return <Icon className={iconSizes[size]} />
+    }
+
+    return <span className="font-semibold">{index + 1}</span>
+  }
+
+  return (
+    <div
+      className={cn(
+        "rounded-full flex items-center justify-center transition-all duration-300",
+        sizeClasses[size],
+        statusClasses[step.status],
+        animated && step.status === "current" && "animate-pulse"
+      )}
+    >
+      {renderContent()}
+    </div>
+  )
+}
+
+interface StepConnectorProps {
+  status: CheckoutStepStatus
+  nextStatus: CheckoutStepStatus
+  orientation: "horizontal" | "vertical"
+}
+
+function StepConnector({ status, nextStatus, orientation }: StepConnectorProps) {
+  const isCompleted = status === "completed" || status === "skipped"
+
+  return (
+    <div
+      className={cn(
+        "transition-all duration-500",
+        orientation === "horizontal"
+          ? "flex-1 h-0.5 mx-2 min-w-[20px]"
+          : "w-0.5 min-h-[32px] mx-auto my-1",
+        isCompleted ? "bg-green-500" : "bg-muted-foreground/30"
+      )}
+    />
+  )
+}
+
+interface StepItemProps {
+  step: CheckoutStep & { status: CheckoutStepStatus }
+  index: number
+  isLast: boolean
+  nextStatus?: CheckoutStepStatus
+}
+
+function StepItem({ step, index, isLast, nextStatus }: StepItemProps) {
+  const {
+    orientation,
+    size,
+    clickable,
+    allowPreviousOnly,
+    currentStep,
+    goToStep,
+  } = useCheckoutStepperContext()
+
+  const isClickable =
+    clickable &&
+    !step.disabled &&
+    (allowPreviousOnly ? index < currentStep : index !== currentStep)
+
+  const labelSizes = {
+    sm: "text-xs",
+    md: "text-sm",
+    lg: "text-base",
+  }
+
+  const descSizes = {
+    sm: "text-[10px]",
+    md: "text-xs",
+    lg: "text-sm",
+  }
+
+  const handleClick = async () => {
+    if (isClickable) {
+      await goToStep(index)
+    }
+  }
+
+  if (orientation === "vertical") {
+    return (
+      <div className="flex">
+        <div className="flex flex-col items-center">
+          <button
+            type="button"
+            onClick={handleClick}
+            disabled={!isClickable}
+            className={cn(
+              "flex items-center",
+              isClickable && "cursor-pointer hover:opacity-80",
+              !isClickable && "cursor-default"
+            )}
+            aria-current={step.status === "current" ? "step" : undefined}
+          >
+            <StepIndicator step={step} index={index} />
+          </button>
+          {!isLast && (
+            <StepConnector
+              status={step.status}
+              nextStatus={nextStatus || "pending"}
+              orientation="vertical"
+            />
+          )}
+        </div>
+        <div className="ml-4 pb-8">
+          <button
+            type="button"
+            onClick={handleClick}
+            disabled={!isClickable}
+            className={cn(
+              "text-left",
+              isClickable && "cursor-pointer hover:opacity-80",
+              !isClickable && "cursor-default"
+            )}
+          >
+            <p
+              className={cn(
+                "font-semibold",
+                labelSizes[size],
+                step.status === "current"
+                  ? "text-foreground"
+                  : step.status === "completed"
+                  ? "text-green-600 dark:text-green-400"
+                  : "text-muted-foreground",
+                step.disabled && "opacity-50"
+              )}
+            >
+              {step.title}
+              {step.optional && (
+                <span className="ml-2 text-muted-foreground font-normal text-xs">
+                  (Optional)
+                </span>
+              )}
+            </p>
+            {step.description && (
+              <p className={cn("text-muted-foreground mt-0.5", descSizes[size])}>
+                {step.description}
+              </p>
+            )}
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  // Horizontal orientation
+  return (
+    <>
+      <div className="flex flex-col items-center flex-shrink-0">
+        <button
+          type="button"
+          onClick={handleClick}
+          disabled={!isClickable}
+          className={cn(
+            "flex flex-col items-center gap-2",
+            isClickable && "cursor-pointer hover:opacity-80",
+            !isClickable && "cursor-default"
+          )}
+          aria-current={step.status === "current" ? "step" : undefined}
+        >
+          <StepIndicator step={step} index={index} />
+          <div className="text-center min-w-[60px] max-w-[100px]">
+            <p
+              className={cn(
+                "font-semibold truncate",
+                labelSizes[size],
+                step.status === "current"
+                  ? "text-foreground"
+                  : step.status === "completed"
+                  ? "text-green-600 dark:text-green-400"
+                  : "text-muted-foreground",
+                step.disabled && "opacity-50"
+              )}
+            >
+              {step.title}
+            </p>
+            {step.description && (
+              <p
+                className={cn(
+                  "text-muted-foreground mt-0.5 hidden md:block truncate",
+                  descSizes[size]
+                )}
+              >
+                {step.description}
+              </p>
+            )}
+          </div>
+        </button>
+      </div>
+      {!isLast && (
+        <StepConnector
+          status={step.status}
+          nextStatus={nextStatus || "pending"}
+          orientation="horizontal"
+        />
+      )}
+    </>
+  )
+}
+
+// ============================================
+// STEP CONTENT WRAPPER
+// ============================================
+
+interface StepContentProps {
+  children: React.ReactNode
+  isActive: boolean
+  direction: "slide" | "fade" | "scale"
+  animated: boolean
+}
+
+function StepContent({ children, isActive, direction, animated }: StepContentProps) {
+  const [shouldRender, setShouldRender] = React.useState(isActive)
+
+  React.useEffect(() => {
+    if (isActive) {
+      setShouldRender(true)
+    } else if (animated) {
+      const timer = setTimeout(() => setShouldRender(false), 300)
+      return () => clearTimeout(timer)
+    } else {
+      setShouldRender(false)
+    }
+  }, [isActive, animated])
+
+  if (!shouldRender) return null
+
+  const animationClasses = {
+    slide: cn(
+      "transition-all duration-300",
+      isActive
+        ? "opacity-100 translate-x-0"
+        : "opacity-0 translate-x-8"
+    ),
+    fade: cn(
+      "transition-opacity duration-300",
+      isActive ? "opacity-100" : "opacity-0"
+    ),
+    scale: cn(
+      "transition-all duration-300",
+      isActive
+        ? "opacity-100 scale-100"
+        : "opacity-0 scale-95"
+    ),
+  }
+
+  return (
+    <div className={animated ? animationClasses[direction] : undefined}>
+      {children}
+    </div>
+  )
+}
+
+// ============================================
+// SUMMARY SIDEBAR
+// ============================================
+
+interface SummarySidebarProps {
+  steps: (CheckoutStep & { status: CheckoutStepStatus })[]
+  position: "left" | "right"
+  className?: string
+}
+
+function SummarySidebar({ steps, position, className }: SummarySidebarProps) {
+  const completedSteps = steps.filter(
+    (s) => s.status === "completed" || s.status === "skipped"
+  )
+
+  return (
+    <div
+      className={cn(
+        "w-full lg:w-80 p-4 bg-muted/50 rounded-lg border",
+        position === "left" ? "lg:order-first" : "lg:order-last",
+        className
+      )}
+    >
+      <h3 className="font-semibold text-lg mb-4">Order Summary</h3>
+      <div className="space-y-4">
+        {completedSteps.map((step) => (
+          <div key={step.id} className="pb-3 border-b border-border last:border-0">
+            <div className="flex items-center gap-2 mb-1">
+              <Check className="h-4 w-4 text-green-500" />
+              <span className="font-medium text-sm">{step.title}</span>
+            </div>
+            {step.summary && (
+              <div className="text-sm text-muted-foreground ml-6">
+                {step.summary}
+              </div>
+            )}
+          </div>
+        ))}
+        {completedSteps.length === 0 && (
+          <p className="text-sm text-muted-foreground">
+            Complete steps to see your order summary.
+          </p>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// ============================================
+// NAVIGATION BUTTONS
+// ============================================
+
+export interface CheckoutNavigationProps {
+  /** Custom class name */
+  className?: string
+  /** Custom labels */
+  labels?: {
+    back?: string
+    next?: string
+    skip?: string
+    complete?: string
+    processing?: string
+  }
+}
+
+export function CheckoutNavigation({
+  className,
+  labels = {},
+}: CheckoutNavigationProps) {
+  const {
+    currentStep,
+    currentStepData,
+    isFirstStep,
+    isLastStep,
+    isValidating,
+    isLoading,
+    validationError,
+    nextStep,
+    prevStep,
+    skipStep,
+    completeCheckout,
+  } = useCheckoutStepperContext()
+
+  const {
+    back = "Back",
+    next = "Continue",
+    skip = "Skip",
+    complete = "Complete Order",
+    processing = "Processing...",
+  } = labels
+
+  const isProcessing = isValidating || isLoading
+
+  return (
+    <div className={cn("space-y-4", className)}>
+      {validationError && (
+        <div className="flex items-center gap-2 p-3 bg-destructive/10 text-destructive rounded-lg text-sm">
+          <AlertCircle className="h-4 w-4 flex-shrink-0" />
+          <span>{validationError}</span>
+        </div>
+      )}
+      <div className="flex items-center justify-between gap-4">
+        <button
+          type="button"
+          onClick={prevStep}
+          disabled={isFirstStep || isProcessing}
+          className={cn(
+            "flex items-center gap-2 px-4 py-2.5 text-sm font-medium rounded-lg border transition-all",
+            isFirstStep || isProcessing
+              ? "opacity-50 cursor-not-allowed bg-muted"
+              : "hover:bg-muted"
+          )}
+        >
+          <ChevronLeft className="h-4 w-4" />
+          {back}
+        </button>
+
+        <div className="flex items-center gap-2">
+          {currentStepData?.optional && !isLastStep && (
+            <button
+              type="button"
+              onClick={skipStep}
+              disabled={isProcessing}
+              className={cn(
+                "flex items-center gap-2 px-4 py-2.5 text-sm font-medium rounded-lg transition-all",
+                "text-muted-foreground hover:text-foreground hover:bg-muted",
+                isProcessing && "opacity-50 cursor-not-allowed"
+              )}
+            >
+              <SkipForward className="h-4 w-4" />
+              {skip}
+            </button>
+          )}
+
+          <button
+            type="button"
+            onClick={isLastStep ? completeCheckout : nextStep}
+            disabled={isProcessing}
+            className={cn(
+              "flex items-center gap-2 px-6 py-2.5 text-sm font-medium rounded-lg transition-all",
+              "bg-primary text-primary-foreground",
+              isProcessing
+                ? "opacity-70 cursor-not-allowed"
+                : "hover:bg-primary/90"
+            )}
+          >
+            {isProcessing ? (
+              <>
+                <Loader2 className="h-4 w-4 animate-spin" />
+                {processing}
+              </>
+            ) : isLastStep ? (
+              <>
+                {complete}
+                <Check className="h-4 w-4" />
+              </>
+            ) : (
+              <>
+                {next}
+                <ChevronRight className="h-4 w-4" />
+              </>
+            )}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ============================================
+// PROGRESS BAR
+// ============================================
+
+export interface CheckoutProgressBarProps {
+  className?: string
+}
+
+export function CheckoutProgressBar({ className }: CheckoutProgressBarProps) {
+  const { currentStep, totalSteps, stepsWithStatus } = useCheckoutStepperContext()
+
+  const completedCount = stepsWithStatus.filter(
+    (s) => s.status === "completed" || s.status === "skipped"
+  ).length
+
+  const progress = Math.round((completedCount / totalSteps) * 100)
+
+  return (
+    <div className={cn("space-y-2", className)}>
+      <div className="flex justify-between text-sm">
+        <span className="text-muted-foreground">
+          Step {currentStep + 1} of {totalSteps}
+        </span>
+        <span className="font-medium">{progress}% complete</span>
+      </div>
+      <div className="h-2 bg-muted rounded-full overflow-hidden">
+        <div
+          className="h-full bg-primary transition-all duration-500 ease-out rounded-full"
+          style={{ width: `${progress}%` }}
+        />
+      </div>
+    </div>
+  )
+}
+
+// ============================================
+// MAIN COMPONENT
+// ============================================
+
+export function WakaCheckoutStepper({
+  steps,
+  currentStep: controlledStep,
+  onStepChange,
+  onComplete,
+  orientation = "horizontal",
+  size = "md",
+  clickable = true,
+  allowPreviousOnly = true,
+  showContent = true,
+  showSummary = false,
+  summaryPosition = "right",
+  animated = true,
+  animationDirection = "slide",
+  isLoading = false,
+  className,
+  labels,
+}: CheckoutStepperProps) {
+  const stepper = useCheckoutStepper({
+    initialStep: controlledStep ?? 0,
+    steps,
+    onStepChange,
+    onComplete,
+    validateOnNext: true,
+  })
+
+  // Sync with controlled step if provided
+  React.useEffect(() => {
+    if (controlledStep !== undefined && controlledStep !== stepper.currentStep) {
+      stepper.goToStep(controlledStep)
+    }
+  }, [controlledStep])
+
+  const contextValue: CheckoutStepperContextValue = {
+    ...stepper,
+    orientation,
+    size,
+    clickable,
+    allowPreviousOnly,
+    animated,
+    animationDirection,
+    isLoading,
+  }
+
+  return (
+    <CheckoutStepperContext.Provider value={contextValue}>
+      <div className={cn("w-full", className)}>
+        {/* Step indicators */}
+        <nav
+          aria-label="Checkout progress"
+          className={cn(
+            "mb-8",
+            orientation === "horizontal"
+              ? "flex items-start justify-between overflow-x-auto pb-2"
+              : "flex flex-col"
+          )}
+        >
+          {stepper.stepsWithStatus.map((step, index) => (
+            <StepItem
+              key={step.id}
+              step={step}
+              index={index}
+              isLast={index === steps.length - 1}
+              nextStatus={stepper.stepsWithStatus[index + 1]?.status}
+            />
+          ))}
+        </nav>
+
+        {/* Content area */}
+        <div
+          className={cn(
+            "flex flex-col lg:flex-row gap-6",
+            showSummary && summaryPosition === "left" && "lg:flex-row-reverse"
+          )}
+        >
+          {/* Main content */}
+          {showContent && (
+            <div className="flex-1 min-w-0">
+              {steps.map((step, index) => (
+                <StepContent
+                  key={step.id}
+                  isActive={index === stepper.currentStep}
+                  direction={animationDirection}
+                  animated={animated}
+                >
+                  <div className="p-6 rounded-lg border bg-card">
+                    <h2 className="text-xl font-semibold mb-2">{step.title}</h2>
+                    {step.description && (
+                      <p className="text-muted-foreground mb-6">{step.description}</p>
+                    )}
+                    {step.content}
+                  </div>
+                </StepContent>
+              ))}
+
+              {/* Navigation */}
+              <div className="mt-6">
+                <CheckoutNavigation labels={labels} />
+              </div>
+            </div>
+          )}
+
+          {/* Summary sidebar */}
+          {showSummary && (
+            <SummarySidebar
+              steps={stepper.stepsWithStatus}
+              position={summaryPosition}
+            />
+          )}
+        </div>
+      </div>
+    </CheckoutStepperContext.Provider>
+  )
+}
+
+// ============================================
+// EXPORTS
+// ============================================
+
+export default WakaCheckoutStepper