@snowcone-app/ui 0.1.43 → 0.2.0

package/src/patterns/ShopProvider.tsx

@@ -0,0 +1,603 @@
+"use client";
+
+import React, {
+  createContext,
+  useState,
+  useCallback,
+  type ReactNode,
+  useRef,
+  useEffect,
+} from "react";
+import type { Artwork } from "../patterns/Product";
+import type { CatalogProduct } from "@snowcone-app/sdk";
+
+// Image update request for queuing
+export interface ImageUpdateRequest {
+  id: string; // Unique identifier for this request
+  execute: () => void; // Function to execute the update
+  priority?: number; // Optional priority (higher = more important)
+  url?: string; // Optional URL to check against cache
+}
+
+export interface ShopContextValue {
+  // Shop configuration
+  endpoint?: string;
+
+  // Artwork selection
+  artworks: Artwork[];
+  selectedArtwork?: Artwork;
+  addArtwork: (artwork: Artwork) => void;
+  setSelectedArtwork: (artwork: Artwork | undefined) => void;
+
+  // Image generation throttling
+  queueImageUpdate: (request: ImageUpdateRequest) => void;
+  cancelImageUpdate: (id: string) => void;
+
+  // Product data caching (for performance optimization)
+  getProduct: (productId: string) => CatalogProduct | undefined;
+  addProduct: (product: CatalogProduct) => void;
+  addProducts: (products: CatalogProduct[]) => void;
+  clearProductCache: () => void;
+
+  // Future shop-level features:
+  // currency?: string;
+  // theme?: 'light' | 'dark';
+  // cartItems?: CartItem[];
+  // addToCart?: (item: CartItem) => void;
+}
+
+export const ShopContext = createContext<ShopContextValue | undefined>(
+  undefined
+);
+
+export interface ShopProps {
+  children: ReactNode;
+  endpoint?: string;
+  mockupUrl?: string;
+  /**
+   * Public image-CDN resolver host (`img.snowcone.app` in prod; the
+   * workspace-local `img` host in dev). Static `<img>` builders use this so the
+   * resolver can sign the render URL. Defaults to `img.snowcone.app` when unset.
+   */
+  resolverUrl?: string;
+  /**
+   * Your public Shop ID (the same value used as `&shop=` in mockup/buy URLs).
+   * Falls back to NEXT_PUBLIC_SNOWCONE_SHOP_ID. Omit for demo mode.
+   */
+  shop?: string;
+  /**
+   * Optional async signer for **L3 (signed-URL) shops**. The UI builds public
+   * mockup `<img>` URLs on the client; a shop at `require_signed_urls` rejects
+   * any URL without an `&signature`. Provide a function that returns the signed
+   * URL — typically a thin call to your own `/api/sign` BFF (the secret stays on
+   * your server) — and the UI signs every static mockup URL through it before
+   * rendering. Omit for L0 shops; URLs render as built.
+   *
+   * Build it with the SDK's batching `bffSigner` (a grid of N images makes ~1
+   * `/api/sign` request, not N), or pass your own `(url) => Promise<string>`.
+   *
+   * @example
+   * ```tsx
+   * import { bffSigner } from "@snowcone-app/sdk";
+   * const signMockupUrl = bffSigner("/api/sign"); // create once (stable)
+   * <Shop shop={shopId} signMockupUrl={signMockupUrl}>…</Shop>
+   * ```
+   */
+  signMockupUrl?: (url: string) => Promise<string>;
+  /**
+   * Initial artwork to select on mount (avoids layout shift)
+   */
+  initialArtwork?: Artwork;
+}
+
+/**
+ * Shop - Global shop context provider with artwork and image throttling
+ *
+ * A pattern component that provides centralized state management for shop-wide
+ * concerns like artwork selection, product caching, and coordinated image generation
+ * throttling. Wrap your entire app (or shop section) in this provider.
+ *
+ * Features:
+ * - Centralized artwork state shared across all Product instances
+ * - Image update queueing with intelligent throttling (5 images/sec)
+ * - Product data caching for performance
+ * - LRU URL cache to bypass throttling for repeated requests
+ * - Per-component throttling (500ms) to prevent rapid updates
+ * - Priority-based queue processing
+ * - Automatic SDK configuration
+ * - Mode/endpoint configuration cascade to child components
+ *
+ * **Image Throttling:**
+ * - Limits mockup generation to 5 images per second (non-cached)
+ * - Cached URLs bypass throttling entirely
+ * - Per-component throttle prevents same component from spamming
+ * - Priority queue ensures important images load first
+ * - LRU cache (max 100 URLs) remembers recent requests
+ *
+ * **Artwork Management:**
+ * - Centralized artwork collection
+ * - Shared selected artwork across all products
+ * - Automatic sync between Product instances
+ *
+ * **Product Caching:**
+ * - In-memory product cache to reduce API calls
+ * - Add/get/clear cache methods
+ * - Useful for product lists and galleries
+ *
+ * @example
+ * ```tsx
+ * // Basic shop setup
+ * <Shop endpoint="http://localhost:3000">
+ *   <ProductList limit={12}>
+ *     <ProductCard variant="overlay" />
+ *   </ProductList>
+ * </Shop>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple products sharing artwork state
+ * <Shop mockupUrl="https://api.example.com">
+ *   <ArtSelector />
+ *
+ *   <div className="grid grid-cols-2 gap-4">
+ *     <Product productId="shirt-123">
+ *       <ProductImage />
+ *     </Product>
+ *     <Product productId="mug-456">
+ *       <ProductImage />
+ *     </Product>
+ *   </div>
+ * </Shop>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With environment variables (Next.js)
+ * // .env.local:
+ * // NEXT_PUBLIC_MERCH_ENDPOINT=http://localhost:3000
+ * // NEXT_PUBLIC_MERCH_MOCKUP_URL=https://mockup.example.com
+ * // NEXT_PUBLIC_SNOWCONE_SHOP_ID=acc_123
+ *
+ * <Shop>
+ *   <YourApp />
+ * </Shop>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Access shop context in child components
+ * function MyComponent() {
+ *   const shop = useShopOptional();
+ *
+ *   return (
+ *     <div>
+ *       <p>Artworks: {shop?.artworks.length}</p>
+ *
+ *       <button onClick={() => shop?.setSelectedArtwork(artwork)}>
+ *         Select Artwork
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Product caching for performance
+ * function ProductCatalog() {
+ *   const shop = useShop();
+ *
+ *   useEffect(() => {
+ *     // Cache products after fetching
+ *     fetchProducts().then(products => {
+ *       shop.addProducts(products);
+ *     });
+ *   }, []);
+ *
+ *   // Later, retrieve from cache
+ *   const cachedProduct = shop.getProduct('shirt-123');
+ * }
+ * ```
+ *
+ * @param children - Child components that will have access to shop context
+ * @param endpoint - API endpoint URL (falls back to NEXT_PUBLIC_MERCH_ENDPOINT)
+ * @param mockupUrl - Mockup generation API URL (falls back to NEXT_PUBLIC_MERCH_MOCKUP_URL)
+ * @param shop - Your public Shop ID (falls back to NEXT_PUBLIC_SNOWCONE_SHOP_ID)
+ */
+export function Shop({
+  children,
+  endpoint,
+  mockupUrl,
+  resolverUrl,
+  shop,
+  signMockupUrl,
+  initialArtwork,
+}: ShopProps) {
+  // Publish runtime config on `window.snowcone` so the internal live-preview
+  // builder (`mockupUrl()`) resolves the same base/shop on the client. The
+  // global SDK `config()` singleton was removed with the image-CDN redesign
+  // (ADR-0075 §7) — the public developer path is now `getMockupUrl({ shop })`.
+  if (typeof window !== "undefined") {
+    const snow = ((window as any).snowcone ||= {});
+    if (mockupUrl) snow.mockupUrl = mockupUrl;
+    if (resolverUrl) snow.resolver = resolverUrl;
+    if (endpoint) snow.endpoint = endpoint;
+    if (shop) snow.shop = shop;
+    // L3 signer (see ShopProps.signMockupUrl). Static mockup `<img>` builders
+    // read this to sign URLs before rendering.
+    if (signMockupUrl) snow.signMockupUrl = signMockupUrl;
+  }
+
+  // Run configuration checks in development
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'development' && typeof window !== 'undefined') {
+      // Delay check to ensure DOM is ready
+      setTimeout(() => {
+        import('../utils/dev-warnings').then(({ runConfigChecks }) => {
+          runConfigChecks();
+        });
+      }, 1000);
+    }
+  }, []);
+  const [artworks, setArtworks] = useState<Artwork[]>([]);
+  const [selectedArtwork, setSelectedArtworkState] = useState<
+    Artwork | undefined
+  >(initialArtwork);
+
+  // Product data cache (use ref to avoid changing reference)
+  const productCacheRef = useRef<Map<string, CatalogProduct>>(new Map());
+
+  // Image update queue management
+  const updateQueueRef = useRef<Map<string, ImageUpdateRequest>>(new Map());
+  const processingRef = useRef<boolean>(false);
+  const processTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const recentProcessTimesRef = useRef<number[]>([]);
+  const componentLastUpdateRef = useRef<Map<string, number>>(new Map());
+  const componentTimeoutsRef = useRef<Map<string, NodeJS.Timeout>>(new Map());
+
+  // URL cache for tracking recently requested images (LRU with max 100 entries)
+  const urlCacheRef = useRef<Set<string>>(new Set());
+  const urlCacheOrderRef = useRef<string[]>([]);
+
+  const addArtwork = useCallback((artwork: Artwork) => {
+    setArtworks((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];
+    });
+  }, []);
+
+  const setSelectedArtwork = useCallback((artwork: Artwork | undefined) => {
+    setSelectedArtworkState(artwork);
+  }, []);
+
+  // Product cache methods
+  const getProduct = useCallback((productId: string) => {
+    return productCacheRef.current.get(productId);
+  }, []);
+
+  const addProduct = useCallback((product: CatalogProduct) => {
+    productCacheRef.current.set(product.id, product);
+  }, []);
+
+  const addProducts = useCallback((products: CatalogProduct[]) => {
+    products.forEach((product) => {
+      productCacheRef.current.set(product.id, product);
+    });
+  }, []);
+
+  const clearProductCache = useCallback(() => {
+    productCacheRef.current.clear();
+  }, []);
+
+  // Add URL to cache (LRU with max 100 entries)
+  const addToUrlCache = useCallback((url: string) => {
+    if (!url) return;
+
+    // If already in cache, move to end (most recently used)
+    if (urlCacheRef.current.has(url)) {
+      const index = urlCacheOrderRef.current.indexOf(url);
+      if (index > -1) {
+        urlCacheOrderRef.current.splice(index, 1);
+      }
+    }
+
+    // Add to end of order list
+    urlCacheOrderRef.current.push(url);
+    urlCacheRef.current.add(url);
+
+    // If over 100 entries, remove oldest
+    if (urlCacheOrderRef.current.length > 100) {
+      const oldestUrl = urlCacheOrderRef.current.shift();
+      if (oldestUrl) {
+        urlCacheRef.current.delete(oldestUrl);
+      }
+    }
+
+  }, []);
+
+  // Check if URL is in cache
+  const isUrlCached = useCallback((url: string): boolean => {
+    return url ? urlCacheRef.current.has(url) : false;
+  }, []);
+
+  // Process the queue - allows up to 5 simultaneous images per second
+  const processQueue = useCallback(() => {
+    if (processingRef.current || updateQueueRef.current.size === 0) {
+      return;
+    }
+
+    processingRef.current = true;
+
+    // Rate limit: 5 images per second (but only for non-cached URLs)
+    const maxPerSecond = 5;
+    const windowMs = 1000; // 1 second window
+
+    // Clean up old timestamps (older than 1 second)
+    const now = Date.now();
+    recentProcessTimesRef.current = recentProcessTimesRef.current.filter(
+      (time) => now - time < windowMs
+    );
+
+    // Get all requests and sort by priority
+    const allRequests = Array.from(updateQueueRef.current.values()).sort(
+      (a, b) => (b.priority || 0) - (a.priority || 0)
+    );
+
+    // Separate cached and non-cached requests
+    const cachedRequests = allRequests.filter(
+      (req) => req.url && isUrlCached(req.url)
+    );
+    const nonCachedRequests = allRequests.filter(
+      (req) => !req.url || !isUrlCached(req.url)
+    );
+
+    // Process cached requests immediately (no rate limit)
+    const toProcess = [...cachedRequests];
+
+    // Add non-cached requests up to available rate limit slots
+    const availableSlots = maxPerSecond - recentProcessTimesRef.current.length;
+
+    if (nonCachedRequests.length > 0) {
+      if (availableSlots <= 0) {
+        // Rate limit reached for non-cached requests
+        const oldestTime = recentProcessTimesRef.current[0];
+        const waitTime = Math.max(0, oldestTime + windowMs - now + 10);
+
+        if (cachedRequests.length === 0) {
+          // No cached requests to process, need to wait
+          processingRef.current = false;
+          processTimeoutRef.current = setTimeout(() => {
+            processQueue();
+          }, waitTime);
+          return;
+        }
+        // Otherwise process cached requests and wait for non-cached
+      } else {
+        // Add non-cached requests up to available slots
+        toProcess.push(...nonCachedRequests.slice(0, availableSlots));
+      }
+    }
+
+    if (toProcess.length > 0) {
+      const cachedCount = cachedRequests.length;
+      const nonCachedCount = toProcess.length - cachedCount;
+
+
+      // Remove from queue and track
+      toProcess.forEach((request) => {
+        updateQueueRef.current.delete(request.id);
+
+        // Only count non-cached requests against rate limit
+        if (!request.url || !isUrlCached(request.url)) {
+          recentProcessTimesRef.current.push(now);
+        }
+
+        // Track when this component was last updated (for component throttling)
+        componentLastUpdateRef.current.set(request.id, now);
+      });
+
+      // Execute all requests
+      toProcess.forEach((request) => {
+        try {
+          request.execute();
+          // Add URL to cache if provided and not already cached
+          if (request.url && !isUrlCached(request.url)) {
+            addToUrlCache(request.url);
+          }
+        } catch (error) {
+          console.error("[Shop] Error executing image update:", error);
+        }
+      });
+    }
+
+    processingRef.current = false;
+
+    // If more updates in queue, check again after a short delay
+    if (updateQueueRef.current.size > 0) {
+      // Check again soon to see if we can process more
+      processTimeoutRef.current = setTimeout(() => {
+        processQueue();
+      }, 100); // Check every 100ms for available slots
+    }
+  }, [addToUrlCache, isUrlCached]);
+
+  // Track the last URL requested by each component (for deduplication)
+  const componentLastUrlRef = useRef<Map<string, string>>(new Map());
+
+  // Queue an image update with per-component throttling (bypassed for cached URLs)
+  const queueImageUpdate = useCallback(
+    (request: ImageUpdateRequest) => {
+      const componentThrottle = 500; // 500ms per component
+      const now = Date.now();
+
+      // Cancel any existing timeout for this component (prevents orphaned timeouts)
+      const existingTimeout = componentTimeoutsRef.current.get(request.id);
+      if (existingTimeout) {
+        clearTimeout(existingTimeout);
+        componentTimeoutsRef.current.delete(request.id);
+      }
+
+      // Deduplicate: Skip if this component just requested the exact same URL
+      // This handles React StrictMode double-invocations and rapid identical requests
+      const lastUrl = componentLastUrlRef.current.get(request.id);
+      if (request.url && lastUrl === request.url) {
+        // Same URL as last request - skip entirely
+        return;
+      }
+
+      // Track this URL as the last requested for this component
+      if (request.url) {
+        componentLastUrlRef.current.set(request.id, request.url);
+      }
+
+      // Check if URL is cached - if so, bypass throttling
+      const isCached = request.url && isUrlCached(request.url);
+
+      if (isCached) {
+      } else {
+        // Check if this component updated recently (only for non-cached URLs)
+        const lastUpdate = componentLastUpdateRef.current.get(request.id);
+        if (lastUpdate) {
+          const timeSinceLastUpdate = now - lastUpdate;
+          if (timeSinceLastUpdate < componentThrottle) {
+            // Component is throttled, update the queued request but don't process yet
+            updateQueueRef.current.set(request.id, request);
+
+            // Schedule processing after throttle period and track the timeout
+            const timeoutId = setTimeout(() => {
+              componentTimeoutsRef.current.delete(request.id);
+              if (!processingRef.current) {
+                processQueue();
+              }
+            }, componentThrottle - timeSinceLastUpdate);
+            componentTimeoutsRef.current.set(request.id, timeoutId);
+            return;
+          }
+        }
+      }
+
+      // Add or replace the request in the queue
+      updateQueueRef.current.set(request.id, request);
+
+      // If not already processing, start processing
+      if (!processingRef.current) {
+        processQueue();
+      }
+    },
+    [processQueue, isUrlCached]
+  );
+
+  // Cancel a queued image update (when component unmounts)
+  const cancelImageUpdate = useCallback((id: string) => {
+    if (updateQueueRef.current.has(id)) {
+      updateQueueRef.current.delete(id);
+    }
+    // Also clean up the last update timestamp and last URL
+    componentLastUpdateRef.current.delete(id);
+    componentLastUrlRef.current.delete(id);
+
+    // Cancel any pending timeout for this component
+    const timeout = componentTimeoutsRef.current.get(id);
+    if (timeout) {
+      clearTimeout(timeout);
+      componentTimeoutsRef.current.delete(id);
+    }
+  }, []);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (processTimeoutRef.current) {
+        clearTimeout(processTimeoutRef.current);
+      }
+      // Clear all component timeouts
+      componentTimeoutsRef.current.forEach((timeout) => clearTimeout(timeout));
+      componentTimeoutsRef.current.clear();
+    };
+  }, []);
+
+  const contextValue: ShopContextValue = {
+    endpoint,
+    artworks,
+    selectedArtwork,
+    addArtwork,
+    setSelectedArtwork,
+    queueImageUpdate,
+    cancelImageUpdate,
+    getProduct,
+    addProduct,
+    addProducts,
+    clearProductCache,
+  };
+
+  return (
+    <ShopContext.Provider value={contextValue}>{children}</ShopContext.Provider>
+  );
+}
+
+/**
+ * useShop - Access shop-level state and methods
+ *
+ * Common use: Build custom art selectors with full control over UI/UX
+ *
+ * @see https://developers.snowcone.app/docs/react/components/select-artwork
+ *
+ * @example
+ * ```tsx
+ * // Custom artwork selector
+ * function MyCustomSelector() {
+ *   const { setSelectedArtwork } = useShop();
+ *
+ *   const selectArtwork = async (url: string) => {
+ *     const img = new Image();
+ *     img.onload = () => {
+ *       setSelectedArtwork({
+ *         type: 'regular',
+ *         src: url,
+ *         width: img.naturalWidth,
+ *         height: img.naturalHeight,
+ *         aspectRatio: img.naturalWidth / img.naturalHeight,
+ *       });
+ *     };
+ *     img.src = url;
+ *   };
+ *
+ *   return <button onClick={() => selectArtwork(url)}>Select</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Access artwork collection
+ * function ArtworkList() {
+ *   const { artworks, selectedArtwork } = useShop();
+ *   return <p>Total: {artworks.length}</p>;
+ * }
+ * ```
+ *
+ * @throws {Error} If used outside of Shop provider
+ * @returns {ShopContextValue} Shop context value
+ */
+export function useShop() {
+  const context = React.useContext(ShopContext);
+  if (!context) {
+    throw new Error("useShop must be used within a Shop provider");
+  }
+  return context;
+}
+
+/**
+ * useShopOptional - Optional access to shop-level state
+ *
+ * Same as useShop() but returns undefined if not within a Shop provider
+ * instead of throwing an error.
+ *
+ * @returns {ShopContextValue | undefined} Shop context value or undefined
+ */
+export function useShopOptional() {
+  return React.useContext(ShopContext);
+}