@snowcone-app/ui 0.1.42 → 0.2.0

package/src/composed/AddToCart.tsx

@@ -0,0 +1,229 @@
+"use client";
+
+import React, { useState, useEffect } from "react";
+import { useProduct, useProductOptional } from "../patterns/Product";
+import { useShopOptional } from "../patterns/ShopProvider";
+import {
+  createCartDetail,
+  simulateCartOperation,
+  validateProductSelection,
+} from "@snowcone-app/sdk";
+import { checkProviders } from "../utils/devWarnings";
+
+export interface AddToCartProps {
+  text?: string;
+  loadingText?: string;
+  successText?: string;
+  disabled?: boolean;
+  className?: string;
+  quantity?: number;
+  onClick?: (cartDetail: any) => void;
+  onError?: (error: Error) => void;
+  simulateDelay?: number;
+}
+
+/**
+ * AddToCart - Add to cart button with validation and loading states
+ *
+ * A composed component that provides a complete add-to-cart experience with
+ * automatic validation, loading states, success feedback, and cart detail creation.
+ * Integrates with Product context for seamless variant and pricing handling.
+ *
+ * Features:
+ * - Automatic selection validation before allowing add
+ * - Loading state with customizable text
+ * - Success state with visual feedback (green background)
+ * - Automatic cart detail generation with variant info
+ * - Simulated delay for cart operations
+ * - Screen reader announcements for state changes
+ * - Accessible with ARIA labels and busy states
+ * - Disabled state when selection is invalid
+ * - CSS custom property support for theming
+ *
+ * **Validation:**
+ * - Ensures all required options are selected
+ * - Checks variant availability
+ * - Validates against product combinations
+ * - Disables button when invalid
+ *
+ * **Context Integration:**
+ * - Must be used within a `Product` context provider
+ * - Automatically uses current selection from context
+ * - Accesses pricing and variant data
+ *
+ * @example
+ * ```tsx
+ * // Basic usage within Product context
+ * <Product productId="shirt-123">
+ *   <ProductOptions />
+ *   <AddToCart
+ *     onClick={(cartDetail) => {
+ *       console.log('Added to cart:', cartDetail);
+ *       // Add to your cart state/API
+ *     }}
+ *   />
+ * </Product>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom text and quantity
+ * <AddToCart
+ *   text="Buy Now"
+ *   loadingText="Processing..."
+ *   successText="Added to Cart!"
+ *   quantity={2}
+ *   onClick={(detail) => addToCart(detail)}
+ *   onError={(err) => showNotification(err.message)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom styling
+ * <AddToCart
+ *   className="w-full py-4 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
+ *   text="Add to Bag"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Faster simulation for testing
+ * <AddToCart
+ *   simulateDelay={500}
+ *   onClick={(detail) => console.log(detail)}
+ * />
+ * ```
+ *
+ * @param text - Button text in default state (default: "Add to Bag")
+ * @param loadingText - Button text while adding (default: "Adding...")
+ * @param successText - Button text after successful add (default: "Added!")
+ * @param disabled - Force button to disabled state
+ * @param className - Additional CSS classes for button
+ * @param quantity - Number of items to add (default: 1)
+ * @param onClick - Callback with cart detail after successful add
+ * @param onError - Callback when add fails with error
+ * @param simulateDelay - Delay in ms to simulate cart operation (default: 1000)
+ */
+export function AddToCart({
+  text = "Add to Bag",
+  loadingText = "Adding...",
+  successText = "Added!",
+  disabled = false,
+  className = "",
+  quantity = 1,
+  onClick,
+  onError,
+  simulateDelay = 1000,
+}: AddToCartProps) {
+  const context = useProduct();
+  const shopContext = useShopOptional();
+  const [loading, setLoading] = useState(false);
+  const [success, setSuccess] = useState(false);
+
+  // Dev-mode warning for missing providers
+  useEffect(() => {
+    checkProviders(
+      "AddToCart",
+      {
+        product: context,
+        shop: shopContext,
+      },
+      "/components/add-to-cart"
+    );
+  }, []);
+
+  const { product, selection, combinations, optionAttributes } = context;
+
+  // Check if selection is valid using the shared validation from ui-core
+  const isValidSelection = () => {
+    return validateProductSelection(
+      optionAttributes || {},
+      selection || {},
+      combinations || []
+    );
+  };
+
+  const isDisabled = disabled || loading || !isValidSelection();
+
+  const handleClick = async () => {
+    if (isDisabled || !product) return;
+
+    try {
+      setLoading(true);
+
+      // Create cart detail using ui-core
+      const cartDetail = createCartDetail({
+        productId: product.id,
+        quantity,
+        selection: selection || {},
+        combinations: combinations || [],
+        attributes: optionAttributes || {},
+      });
+
+      if (!cartDetail) {
+        throw new Error("Invalid selection - unable to create cart detail");
+      }
+
+      // Simulate cart operation delay
+      await simulateCartOperation(simulateDelay);
+
+      // Call onClick handler with cart detail
+      onClick?.(cartDetail);
+
+      // Show success state
+      setSuccess(true);
+
+      // Reset success after 2 seconds
+      setTimeout(() => {
+        setSuccess(false);
+      }, 2000);
+    } catch (error) {
+      onError?.(error as Error);
+      console.error("Add to cart failed:", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const buttonText = loading ? loadingText : success ? successText : text;
+
+  // Default styles that work out of the box - LLM-friendly
+  // These are always applied, then className can override/extend them
+  const defaultStyles = "w-full bg-primary text-primary-foreground hover:bg-primary/90 px-6 py-3 rounded-button font-medium transition-colors";
+
+  const buttonClasses = `
+    ${defaultStyles}
+    ${className || ""}
+    ${loading ? "cursor-wait" : ""}
+    ${isDisabled && !loading ? "opacity-50 cursor-not-allowed" : ""}
+  `.trim();
+
+  // Generate descriptive aria-label
+  const getAriaLabel = () => {
+    if (loading) return loadingText;
+    if (success) return successText;
+    if (!product) return text;
+    return `${text} - ${product.name || 'product'}`;
+  };
+
+  return (
+    <>
+      {/* Screen reader announcements for state changes */}
+      <div className="sr-only" role="status" aria-live="polite" aria-atomic="true">
+        {loading ? loadingText : success ? successText : ''}
+      </div>
+
+      <button
+        className={buttonClasses}
+        disabled={isDisabled}
+        onClick={handleClick}
+        aria-label={getAriaLabel()}
+        aria-busy={loading}
+      >
+        {buttonText}
+      </button>
+    </>
+  );
+}