@snowcone-app/ui 0.1.43 → 0.2.0

package/src/patterns/Product.tsx

@@ -0,0 +1,850 @@
+"use client";
+
+import React, {
+  createContext,
+  useState,
+  useEffect,
+  useMemo,
+  useCallback,
+  useRef,
+} from "react";
+import type { CatalogProduct } from "@snowcone-app/sdk";
+import { getProduct, listProducts } from "@snowcone-app/sdk";
+import { createDevFetcher } from "@snowcone-app/sdk/dev-fetcher";
+import type {
+  OptionAttribute,
+  Combination,
+  OptionSelection,
+  ProductContext as CoreProductContext,
+  ImageAlignment,
+} from "@snowcone-app/sdk";
+
+/**
+ * Available clip shape options for artboards/placements
+ */
+export type ClipShape = 'rectangle' | 'circle' | 'custom';
+import {
+  deriveDefaultSelection,
+  toOptionAttributes,
+  toCombinations,
+  findBestCombination,
+  UniversalContextProvider,
+  createUniversalProvider,
+} from "@snowcone-app/sdk";
+import { useShopOptional } from "../patterns/ShopProvider";
+// NOTE: Realtime functionality has been moved to RealtimeProvider for better performance.
+// Use <RealtimeProvider> to wrap components that need realtime mockup updates.
+// This prevents mockup result updates from causing re-renders in ProductContext consumers.
+
+// Design-related interfaces (previously in DesignContext)
+export interface PlacementDesign {
+  imageUrl: string;
+  alignment: ImageAlignment;
+  tiles?: 0.25 | 0.5 | 1 | 2 | 4;
+  // Future fields can be added here:
+  // filters?: string[];
+  // etc.
+}
+
+export type RegularArtwork = {
+  type: "regular";
+  src: string;
+};
+
+export type SeamlessPattern = {
+  type: "pattern";
+  src: string;
+  tileCount: 0.25 | 0.5 | 1 | 2 | 4;
+};
+
+export type Artwork = RegularArtwork | SeamlessPattern;
+
+// Realtime mockup types
+export interface MockupResult {
+  mockupId: string;
+  imageUrl: string;
+}
+
+export interface RealtimeState {
+  isEnabled: boolean;
+  isConnected: boolean;
+  isConfigured: boolean;
+  mockupResults: MockupResult[];
+  isPendingMockups: boolean;
+  canvasBlobsSent: number;
+  colorBlobsSent: number;
+  lastBlobSentTime: string | null;
+  canvasExportSize: { width: number; height: number };
+  mockupWidth: number;
+  placementDimensions: Array<{
+    label: string;
+    width?: number;
+    height?: number;
+    type: string;
+  }>;
+  // PERFORMANCE: Polling access to mockup results (avoids waiting for throttled state updates)
+  getMockupResultsImmediate?: () => MockupResult[];
+  // Subscribe for immediate notifications when any mockup arrives
+  subscribeMockupResults?: (callback: (results: MockupResult[]) => void) => () => void;
+  // PERFORMANCE: Subscribe for a specific mockupId only (more efficient for HeroProductImage)
+  subscribeMockupResultById?: (mockupId: string, callback: (result: MockupResult) => void) => () => void;
+}
+
+// Extended React Context with update methods and design functionality
+export interface ReactProductContext extends CoreProductContext {
+  updateSelection?: (selection: OptionSelection) => void;
+  currentPrice?: number;
+
+  // Design functionality (previously in DesignProvider)
+  placements: Record<string, PlacementDesign>;
+  artworks: Artwork[];
+  selectedArtwork?: Artwork;
+  selectedPlacement?: string;
+  clipShapes: Record<string, ClipShape>;
+  clipShapeInExport: Record<string, boolean>;
+
+  // Design methods
+  setPlacementDesign: (
+    placement: string,
+    design: Partial<PlacementDesign>
+  ) => void;
+  getPlacementDesign: (placement: string) => PlacementDesign | undefined;
+  addArtwork: (artwork: Artwork) => void;
+  setSelectedArtwork: (artwork: Artwork | undefined) => void;
+  setSelectedPlacement: (placement: string) => void;
+  applyArtworkToPlacement: (placement: string, artwork?: Artwork) => void;
+  setPlacementClipShape: (placement: string, clipShape: ClipShape) => void;
+  getPlacementClipShape: (placement: string) => ClipShape;
+  setClipShapeInExport: (placement: string, includeInExport: boolean) => void;
+  getClipShapeInExport: (placement: string) => boolean;
+
+  // NOTE: Realtime mockup functionality has been moved to RealtimeProvider
+  // Use useRealtime() or useRealtimeOptional() from RealtimeProvider instead
+}
+
+// React Context
+export const ProductContext = createContext<ReactProductContext | undefined>(
+  undefined
+);
+
+/**
+ * Data loading mode for the Product component.
+ *
+ * - "ssr": Server-Side Rendering mode. Product data will be provided via props
+ *   (through RSC streaming or parent component). Never fetches client-side.
+ *   Use this in Next.js App Router pages with Suspense boundaries.
+ *
+ * - "client": Client-Side mode. Component will fetch product data itself.
+ *   Use this for client-only pages or when no server data is available.
+ *
+ * - "auto" (default): Automatic mode. Fetches only if productData is not provided.
+ *   Legacy behavior for backwards compatibility.
+ */
+export type ProductDataMode = "ssr" | "client" | "auto";
+
+export interface ProductProviderProps {
+  children: React.ReactNode;
+  productId?: string;
+  productData?: CatalogProduct; // Allow passing product data directly to skip fetching
+  endpoint?: string;
+  source?: string;
+  fetcher?: typeof fetch;
+  className?: string;
+  initialSelection?: OptionSelection;
+  initialPlacements?: Record<string, PlacementDesign>;
+  renderLoading?: () => React.ReactNode;
+  renderError?: (error: any) => React.ReactNode;
+  /**
+   * Data loading mode. Determines how the component obtains product data.
+   * - "ssr": Wait for productData prop (never fetch). Use with Next.js RSC/Suspense.
+   * - "client": Always fetch client-side.
+   * - "auto": Fetch only if productData not provided (default, legacy behavior).
+   */
+  dataMode?: ProductDataMode;
+  /** @deprecated Use dataMode="ssr" instead. Skip client-side fetching. */
+  skipFetch?: boolean;
+  // NOTE: wsUrl and realtimeMockupWidth have moved to RealtimeProvider
+}
+
+/**
+ * Product - Context provider for product data, variant selection, and design management
+ *
+ * A composed pattern component that provides React context for product information,
+ * variant selection, pricing, artwork management, and placement designs. Acts as the
+ * central state container for product-related components.
+ *
+ * Features:
+ * - Automatic product data fetching from API endpoint
+ * - Variant selection and combination management
+ * - Dynamic price calculation based on selected options
+ * - Design/artwork management with placement-specific designs
+ * - Integration with Shop context for shared artwork state
+ * - Loading and error states with custom render props
+ * - Universal provider sync for cross-framework compatibility
+ * - SSR-friendly with optional data prop to skip fetching
+ *
+ * **Context Provided:**
+ * - Product data and metadata
+ * - Option attributes and combinations
+ * - Current selection and price
+ * - Artwork collection and selected artwork
+ * - Placement designs (alignment, tiles, etc.)
+ * - Methods to update selection, artwork, and placements
+ *
+ * **Integration with Shop:**
+ * - Inherits endpoint from Shop context if available
+ * - Shares artwork state across all Product instances in a Shop
+ * - Falls back to local state if used standalone
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - fetch product by ID
+ * <Product productId="shirt-123">
+ *   <ProductImage />
+ *   <ProductOptions />
+ *   <AddToCart />
+ * </Product>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With initial selection and custom loading
+ * <Product
+ *   productId="shirt-123"
+ *   initialSelection={{ Size: 'M', Color: 'Blue' }}
+ *   renderLoading={() => <Spinner />}
+ *   renderError={(err) => <ErrorMessage error={err} />}
+ * >
+ *   <ProductCard />
+ * </Product>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Standalone with explicit data (no fetching)
+ * <Product
+ *   productData={myProductData}
+ *   initialPlacements={{
+ *     Front: { imageUrl: 'logo.png', alignment: 'center' },
+ *     Back: { imageUrl: 'text.png', alignment: 'top' }
+ *   }}
+ * >
+ *   <ArtAlignment placement="Front" />
+ *   <ProductImage />
+ * </Product>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Shop context
+ * <Shop endpoint="http://localhost:3000">
+ *   <Product productId="shirt-123">
+ *     <ProductImage />
+ *   </Product>
+ *   <Product productId="mug-456">
+ *     <ProductImage />
+ *   </Product>
+ * </Shop>
+ * // Both products share artwork state from Shop
+ * ```
+ *
+ * @param children - Child components that consume product context
+ * @param productId - Product identifier to fetch
+ * @param productData - Explicit product data (skips fetching if provided)
+ * @param endpoint - API endpoint URL (overrides Shop context)
+ * @param source - Source identifier for data fetching (default: "auto")
+ * @param fetcher - Custom fetch function (e.g., for auth headers)
+ * @param className - Additional CSS classes for wrapper div
+ * @param initialSelection - Pre-select variant options (e.g., { Size: 'M', Color: 'Blue' })
+ * @param initialPlacements - Pre-configure placement designs
+ * @param renderLoading - Custom loading UI component
+ * @param renderError - Custom error UI component
+ */
+export function Product({
+  children,
+  productId,
+  productData,
+  endpoint,
+  source = "auto",
+  fetcher,
+  className,
+  initialSelection,
+  initialPlacements,
+  renderLoading,
+  renderError,
+  dataMode = "auto",
+  skipFetch = false, // Deprecated, kept for backwards compatibility
+}: ProductProviderProps) {
+  // Resolve effective mode: skipFetch takes precedence for backwards compatibility
+  const effectiveMode: ProductDataMode = skipFetch ? "ssr" : dataMode;
+
+  const [product, setProduct] = useState<CatalogProduct | undefined>(
+    productData
+  );
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<any>(null);
+  const [selection, setSelection] = useState<OptionSelection>({});
+
+  // Sync productData prop to state when it changes (e.g., from SSR streaming)
+  // This is essential for "ssr" mode where data arrives after initial mount
+  useEffect(() => {
+    if (productData) {
+      setProduct(productData);
+      setLoading(false);
+      setError(null);
+    }
+  }, [productData]);
+
+  // Check if we have a parent Shop context
+  const shopContext = useShopOptional();
+
+  // Use shop context values if available, otherwise use props
+  const effectiveEndpoint = endpoint ?? shopContext?.endpoint;
+
+  // Design state - use shop context if available, otherwise maintain local state
+  // Key the placements by productId to ensure they reset when product changes
+  // Initialize with initialPlacements if provided
+  const [placementsById, setPlacementsById] = useState<
+    Record<string, Record<string, PlacementDesign>>
+  >(() => {
+    if (initialPlacements && productId) {
+      return { [productId]: initialPlacements };
+    }
+    return {};
+  });
+
+  // Store alignment settings per artwork URL
+  // Key structure: { productId: { placement: { artworkUrl: ImageAlignment } } }
+  const [alignmentByArtwork, setAlignmentByArtwork] = useState<
+    Record<string, Record<string, Record<string, ImageAlignment>>>
+  >({});
+
+  // Get current product's placements
+  // IMPORTANT: Use a stable empty object reference to avoid triggering re-renders
+  // when there are no placements. Creating {} inline would create a new object each render.
+  const EMPTY_PLACEMENTS: Record<string, PlacementDesign> = useMemo(() => ({}), []);
+  const placements = productId ? placementsById[productId] || EMPTY_PLACEMENTS : EMPTY_PLACEMENTS;
+  const [localArtworks, setLocalArtworks] = useState<Artwork[]>([]);
+  const [localSelectedArtwork, setLocalSelectedArtwork] = useState<
+    Artwork | undefined
+  >();
+  const [localSelectedPlacement, setLocalSelectedPlacement] = useState<
+    string | undefined
+  >();
+
+  // Clip shapes per placement (keyed by productId -> placementLabel -> ClipShape)
+  const [clipShapesById, setClipShapesById] = useState<
+    Record<string, Record<string, ClipShape>>
+  >({});
+
+  // Clip shape export flag per placement (keyed by productId -> placementLabel -> boolean)
+  const [clipShapeInExportById, setClipShapeInExportById] = useState<
+    Record<string, Record<string, boolean>>
+  >({});
+
+  // Use shop context if available, otherwise use local state
+  const artworks = shopContext?.artworks ?? localArtworks;
+  const selectedArtwork = shopContext?.selectedArtwork ?? localSelectedArtwork;
+  const selectedPlacement = localSelectedPlacement;
+
+  // Get current product's clip shapes (default to rectangle if not set)
+  const clipShapes = productId ? clipShapesById[productId] || {} : {};
+
+  // Get current product's clip shape export flags (default to false if not set)
+  const clipShapeInExport = productId ? clipShapeInExportById[productId] || {} : {};
+
+  // Create universal provider
+  const universalProvider = useMemo(() => {
+    return createUniversalProvider({
+      endpoint: effectiveEndpoint,
+      productId,
+      fetcher,
+      autoLoad: false,
+    });
+  }, [effectiveEndpoint, productId]);
+
+  useEffect(() => {
+    // SSR mode: Never fetch, wait for productData to arrive via props
+    if (effectiveMode === "ssr") {
+      // If productData is already available, initialize selection
+      if (productData) {
+        setProduct(productData);
+
+        // Apply initial placements if provided
+        if (initialPlacements && (productId || productData.id)) {
+          const id = productId || productData.id;
+          setPlacementsById((prev) => {
+            if (!prev[id]) {
+              return { ...prev, [id]: initialPlacements };
+            }
+            return prev;
+          });
+        }
+
+        // Derive initial selection
+        const attrs = toOptionAttributes(productData);
+        const combos = toCombinations(productData);
+        const defaultSelection =
+          initialSelection || deriveDefaultSelection(attrs, combos);
+
+        // Initialize default colors for color placements
+        const colorPlacementDefaults: Record<string, string> = {};
+        if (productData.placements) {
+          productData.placements.forEach((placement: any) => {
+            if (
+              placement.type === "color" &&
+              !defaultSelection[placement.label]
+            ) {
+              colorPlacementDefaults[placement.label] = "#000000";
+            }
+          });
+        }
+
+        const finalSelection = { ...defaultSelection, ...colorPlacementDefaults };
+        setSelection(finalSelection);
+      }
+      // In SSR mode, don't fetch - data will arrive via productData prop
+      return;
+    }
+
+    // Auto mode: Skip fetching if productData was already provided
+    if (effectiveMode === "auto" && productData) {
+      setProduct(productData);
+
+      // Apply initial placements if provided
+      if (initialPlacements && (productId || productData.id)) {
+        const id = productId || productData.id;
+        setPlacementsById((prev) => {
+          if (!prev[id]) {
+            return { ...prev, [id]: initialPlacements };
+          }
+          return prev;
+        });
+      }
+
+      // Derive initial selection
+      const attrs = toOptionAttributes(productData);
+      const combos = toCombinations(productData);
+      const defaultSelection =
+        initialSelection || deriveDefaultSelection(attrs, combos);
+
+      // Initialize default colors for color placements
+      const colorPlacementDefaults: Record<string, string> = {};
+      if (productData.placements) {
+        productData.placements.forEach((placement: any) => {
+          if (
+            placement.type === "color" &&
+            !defaultSelection[placement.label]
+          ) {
+            colorPlacementDefaults[placement.label] = "#000000";
+          }
+        });
+      }
+
+      const finalSelection = { ...defaultSelection, ...colorPlacementDefaults };
+      setSelection(finalSelection);
+      return;
+    }
+
+    // Client mode (or auto mode without productData): Fetch product data
+    let isCancelled = false;
+
+    const loadProduct = async () => {
+      setLoading(true);
+      setError(null);
+
+      const baseUrl = effectiveEndpoint;
+      const customFetcher = fetcher;
+
+      try {
+        let loadedProduct: CatalogProduct | undefined;
+
+        if (productId) {
+          loadedProduct = await getProduct(productId, {
+            baseUrl,
+            fetcher: customFetcher as any,
+          });
+        } else {
+          const { items } = await listProducts({
+            baseUrl,
+            fetcher: customFetcher as any,
+          });
+          loadedProduct = items?.[0];
+        }
+
+        if (isCancelled) return;
+
+        if (loadedProduct) {
+          setProduct(loadedProduct);
+
+          // Apply initial placements if provided and not already set
+          if (initialPlacements && productId) {
+            setPlacementsById((prev) => {
+              if (!prev[productId]) {
+                return { ...prev, [productId]: initialPlacements };
+              }
+              return prev;
+            });
+          }
+
+          // Derive initial selection
+          const attrs = toOptionAttributes(loadedProduct);
+          const combos = toCombinations(loadedProduct);
+          const defaultSelection =
+            initialSelection || deriveDefaultSelection(attrs, combos);
+
+          // Initialize default colors for color placements
+          const colorPlacementDefaults: Record<string, string> = {};
+          if (loadedProduct.placements) {
+            loadedProduct.placements.forEach((placement: any) => {
+              if (
+                placement.type === "color" &&
+                !defaultSelection[placement.label]
+              ) {
+                colorPlacementDefaults[placement.label] = "#000000";
+              }
+            });
+          }
+
+          const finalSelection = {
+            ...defaultSelection,
+            ...colorPlacementDefaults,
+          };
+          setSelection(finalSelection);
+        }
+      } catch (err) {
+        if (isCancelled) return;
+        console.error("Failed to load product:", err);
+        setError(err);
+      } finally {
+        if (!isCancelled) {
+          setLoading(false);
+        }
+      }
+    };
+
+    loadProduct();
+
+    return () => {
+      isCancelled = true;
+    };
+  }, [
+    productId,
+    productData,
+    effectiveEndpoint,
+    fetcher,
+    initialSelection,
+    initialPlacements,
+    effectiveMode,
+  ]);
+
+  // Compute derived values
+  const optionAttributes = useMemo(
+    () => (product ? toOptionAttributes(product) : {}),
+    [product]
+  );
+
+  const combinations = useMemo(
+    () => (product ? toCombinations(product) : []),
+    [product]
+  );
+
+  // Update selection handler - memoized to prevent context re-creation
+  const updateSelection = useCallback((newSelection: OptionSelection) => {
+    setSelection(prev => {
+      const merged = { ...prev, ...newSelection };
+      return merged;
+    });
+  }, []);
+
+  // Design methods (previously in DesignProvider)
+  const setPlacementDesign = useCallback(
+    (placement: string, design: Partial<PlacementDesign>) => {
+      if (!productId) return;
+
+      setPlacementsById((prev) => ({
+        ...prev,
+        [productId]: {
+          ...prev[productId],
+          [placement]: {
+            ...prev[productId]?.[placement],
+            ...design,
+          } as PlacementDesign,
+        },
+      }));
+
+      // If alignment is being set and we have a selected artwork, save it per artwork
+      if (design.alignment && selectedArtwork) {
+        setAlignmentByArtwork((prev) => ({
+          ...prev,
+          [productId]: {
+            ...prev[productId],
+            [placement]: {
+              ...prev[productId]?.[placement],
+              [selectedArtwork.src]: design.alignment!,
+            },
+          },
+        }));
+      }
+    },
+    [productId, selectedArtwork]
+  );
+
+  const getPlacementDesign = useCallback(
+    (placement: string): PlacementDesign | undefined => {
+      const design = placements[placement];
+      return design;
+    },
+    [placements]
+  );
+
+  // Use shop context methods if available, otherwise use local methods
+  const addArtwork = useCallback(
+    (artwork: Artwork) => {
+      if (shopContext) {
+        shopContext.addArtwork(artwork);
+      } else {
+        setLocalArtworks((prev) => {
+          const exists = prev.some((a) => a.src === artwork.src);
+          if (exists) {
+            return prev.map((a) => (a.src === artwork.src ? artwork : a));
+          }
+          return [...prev, artwork];
+        });
+      }
+    },
+    [shopContext]
+  );
+
+  const setSelectedArtwork = useCallback(
+    (artwork: Artwork | undefined) => {
+      if (shopContext) {
+        shopContext.setSelectedArtwork(artwork);
+      } else {
+        setLocalSelectedArtwork(artwork);
+      }
+    },
+    [shopContext]
+  );
+
+  const setSelectedPlacement = useCallback(
+    (placement: string) => {
+      setLocalSelectedPlacement(placement);
+    },
+    []
+  );
+
+  // Update placements when selected artwork changes
+  useEffect(() => {
+    if (selectedArtwork && productId) {
+      setPlacementsById((prev) => {
+        const currentPlacements = prev[productId] || {};
+        const updated = { ...currentPlacements };
+        const savedAlignments = alignmentByArtwork[productId] || {};
+
+        Object.keys(updated).forEach((key) => {
+          // Check if we have a saved alignment for this artwork on this placement
+          const savedAlignment = savedAlignments[key]?.[selectedArtwork.src];
+
+          updated[key] = {
+            ...updated[key],
+            imageUrl: selectedArtwork.src,
+            // Restore saved alignment if it exists, otherwise reset to default (center)
+            alignment: savedAlignment || "center",
+          };
+        });
+        return {
+          ...prev,
+          [productId]: updated,
+        };
+      });
+    }
+  }, [selectedArtwork, productId, alignmentByArtwork]);
+
+  const applyArtworkToPlacement = useCallback(
+    (placement: string, artwork?: Artwork) => {
+      if (artwork) {
+        setPlacementDesign(placement, { imageUrl: artwork.src });
+      }
+    },
+    [setPlacementDesign]
+  );
+
+  const setPlacementClipShape = useCallback(
+    (placement: string, clipShape: ClipShape) => {
+      if (!productId) return;
+
+      setClipShapesById((prev) => ({
+        ...prev,
+        [productId]: {
+          ...prev[productId],
+          [placement]: clipShape,
+        },
+      }));
+    },
+    [productId]
+  );
+
+  const getPlacementClipShape = useCallback(
+    (placement: string): ClipShape => {
+      return clipShapes[placement] || 'rectangle'; // Default to rectangle
+    },
+    [clipShapes]
+  );
+
+  const setClipShapeInExport = useCallback(
+    (placement: string, includeInExport: boolean) => {
+      if (!productId) return;
+
+      setClipShapeInExportById((prev) => ({
+        ...prev,
+        [productId]: {
+          ...prev[productId],
+          [placement]: includeInExport,
+        },
+      }));
+    },
+    [productId]
+  );
+
+  const getClipShapeInExport = useCallback(
+    (placement: string): boolean => {
+      return clipShapeInExport[placement] ?? false; // Default to false (don't include in export)
+    },
+    [clipShapeInExport]
+  );
+
+  // Calculate current price based on selection
+  const currentPrice = useMemo(() => {
+    if (!product) return undefined;
+
+    // Use findBestCombination from ui-core for consistent logic
+    const bestCombination = findBestCombination(
+      selection,
+      combinations,
+      optionAttributes
+    );
+
+    return bestCombination?.price || product.price;
+  }, [product, combinations, selection, optionAttributes]);
+
+  // Create context value with update method and design functionality
+  // MEMOIZED to prevent unnecessary re-renders of context consumers
+  // NOTE: Realtime functionality has been moved to RealtimeProvider
+  const contextValue = useMemo<ReactProductContext>(() => ({
+    product,
+    optionAttributes,
+    combinations,
+    selection,
+    loading,
+    error,
+    updateSelection,
+    currentPrice,
+
+    // Design functionality
+    placements,
+    artworks,
+    selectedArtwork,
+    selectedPlacement,
+    clipShapes,
+    clipShapeInExport,
+    setPlacementDesign,
+    getPlacementDesign,
+    addArtwork,
+    setSelectedArtwork,
+    setSelectedPlacement,
+    applyArtworkToPlacement,
+    setPlacementClipShape,
+    getPlacementClipShape,
+    setClipShapeInExport,
+    getClipShapeInExport,
+  }), [
+    product,
+    optionAttributes,
+    combinations,
+    selection,
+    loading,
+    error,
+    updateSelection,
+    currentPrice,
+    placements,
+    artworks,
+    selectedArtwork,
+    selectedPlacement,
+    clipShapes,
+    clipShapeInExport,
+    setPlacementDesign,
+    getPlacementDesign,
+    addArtwork,
+    setSelectedArtwork,
+    setSelectedPlacement,
+    applyArtworkToPlacement,
+    setPlacementClipShape,
+    getPlacementClipShape,
+    setClipShapeInExport,
+    getClipShapeInExport,
+  ]);
+
+  // Sync with universal provider
+  useEffect(() => {
+    if (product) {
+      universalProvider.getContext().product = product;
+      universalProvider.getContext().optionAttributes = optionAttributes;
+      universalProvider.getContext().combinations = combinations;
+      universalProvider.getContext().selection = selection;
+    }
+  }, [product, optionAttributes, combinations, selection, universalProvider]);
+
+  // Handle loading state
+  if (loading && renderLoading) {
+    return <>{renderLoading()}</>;
+  }
+
+  // Handle error state
+  if (error) {
+    if (renderError) {
+      return <>{renderError(error)}</>;
+    }
+    // Default error UI
+    return <div className="merch-error">Failed to load product</div>;
+  }
+
+  return (
+    <ProductContext.Provider value={contextValue}>
+      <div
+        className={`merch-product ${className || ""}`}
+        data-merch-provider
+      >
+        {children}
+      </div>
+    </ProductContext.Provider>
+  );
+}
+
+// Hook to use product context
+export function useProduct() {
+  const context = React.useContext(ProductContext);
+  if (!context) {
+    throw new Error("useProduct must be used within a Product provider");
+  }
+  return context;
+}
+
+// Optional hook that doesn't throw when not in a Product provider
+export function useProductOptional() {
+  return React.useContext(ProductContext);
+}
+
+// Hook specifically for design functionality (alias for useProduct for backwards compatibility)
+export function useDesign() {
+  const context = React.useContext(ProductContext);
+  if (!context) {
+    throw new Error("useDesign must be used within a Product provider");
+  }
+  return context;
+}
+
+// Optional design hook that doesn't throw when not in a Product provider
+export function useDesignOptional() {
+  return React.useContext(ProductContext);
+}