@snowcone-app/ui 0.1.42 → 0.2.0

package/src/hooks/useProductGallery.ts

@@ -0,0 +1,193 @@
+"use client";
+
+import { useState, useEffect, useMemo, useCallback } from "react";
+import type { CatalogProduct } from "@snowcone-app/sdk";
+import { getProduct, listProducts } from "@snowcone-app/sdk";
+import { createDevFetcher } from "@snowcone-app/sdk/dev-fetcher";
+
+export interface UseProductGalleryOptions {
+  endpoint?: string;
+  mode?: "mock" | "live";
+  limit?: number; // For listProducts when no productIds provided
+}
+
+export interface UseProductGalleryReturn {
+  products: CatalogProduct[];
+  loading: boolean;
+  error: string | null;
+  refetch: () => void;
+}
+
+/**
+ * useProductGallery - Fetch and manage product collections
+ *
+ * A React hook for fetching either specific products by ID or listing all
+ * available products. Handles loading states, errors, and provides refetch
+ * capability. Perfect for product catalogs, related products, and galleries.
+ *
+ * Features:
+ * - Fetch specific products by ID array
+ * - List all products (empty array)
+ * - Loading and error states
+ * - Refetch capability
+ * - Mock/live mode support
+ * - Automatic deduplication via memoization
+ * - Limit for product lists
+ *
+ * **Modes:**
+ * - Specific products: Pass array of IDs `['id1', 'id2']`
+ * - List all: Pass empty array `[]` or omit parameter
+ *
+ * **Use Cases:**
+ * - Product catalog pages
+ * - Related/recommended products
+ * - Search results
+ * - Recently viewed
+ * - User favorites
+ *
+ * @example
+ * ```tsx
+ * // Fetch specific products
+ * const { products, loading, error, refetch } = useProductGallery(
+ *   ['BEEB77', 'AR2P3G'],
+ *   { endpoint: 'http://localhost:3000', mode: 'mock' }
+ * );
+ *
+ * if (loading) return <Spinner />;
+ * if (error) return <Error message={error} onRetry={refetch} />;
+ *
+ * return (
+ *   <div className="grid grid-cols-3 gap-4">
+ *     {products.map(product => (
+ *       <ProductCard key={product.id} product={product} />
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // List all products with limit
+ * const { products, loading } = useProductGallery(
+ *   [], // Empty array = list all
+ *   { mode: 'mock', limit: 12 }
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Use in Remix loader
+ * export async function loader() {
+ *   // Note: In loaders, use SDK functions directly
+ *   // This hook is for client components
+ *   const products = await listProducts({ ... });
+ *   return json({ products });
+ * }
+ *
+ * // Then in component
+ * function ProductGallery() {
+ *   const { products } = useLoaderData<typeof loader>();
+ *   // Or use hook for client-side filtering
+ *   const { products: filtered } = useProductGallery(
+ *     products.map(p => p.id)
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With error handling and retry
+ * function ProductCatalog() {
+ *   const { products, loading, error, refetch } = useProductGallery([], {
+ *     mode: 'live',
+ *     limit: 20
+ *   });
+ *
+ *   if (error) {
+ *     return (
+ *       <div>
+ *         <p>Failed to load: {error}</p>
+ *         <button onClick={refetch}>Retry</button>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   return <ProductGrid products={products} loading={loading} />;
+ * }
+ * ```
+ *
+ * @param productIds - Array of product IDs to fetch (empty array = list all)
+ * @param options - Configuration options
+ * @param options.endpoint - API endpoint URL
+ * @param options.mode - Data source ("mock" or "live", default: "mock")
+ * @param options.limit - Max products to return when listing all (default: 10)
+ * @returns Object with products array, loading state, error, and refetch function
+ */
+export function useProductGallery(
+  productIds: string[] = [], // Make optional - empty array means "list all products"
+  options: UseProductGalleryOptions = {}
+): UseProductGalleryReturn {
+  const { endpoint, mode = "mock", limit = 10 } = options;
+
+  const [products, setProducts] = useState<CatalogProduct[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Memoize the productIds array to prevent infinite loops from array reference changes
+  const memoizedProductIds = useMemo(
+    () => productIds,
+    [JSON.stringify(productIds)]
+  );
+
+  const fetchProducts = useCallback(async () => {
+    try {
+      setLoading(true);
+      setError(null);
+
+      const baseUrl =
+        endpoint ||
+        (window as any)?.snowcone?.endpoint ||
+        "http://192.168.4.32:5175";
+      const customFetcher =
+        mode === "mock" ? createDevFetcher(baseUrl) : undefined;
+
+      let fetchedProducts: CatalogProduct[];
+
+      if (memoizedProductIds.length === 0) {
+        // List all products when no specific IDs provided
+        const response = await listProducts({
+          baseUrl,
+          fetcher: customFetcher as any,
+        });
+        fetchedProducts = response.items.slice(0, limit); // Apply limit
+      } else {
+        // Fetch specific products by ID
+        const productPromises = memoizedProductIds.map((productId) =>
+          getProduct(productId, { baseUrl, fetcher: customFetcher as any })
+        );
+
+        const results = await Promise.all(productPromises);
+        fetchedProducts = results.filter(Boolean) as CatalogProduct[];
+      }
+
+      setProducts(fetchedProducts);
+    } catch (err: any) {
+      console.error("Failed to load products:", err);
+      setError(err.message || "Failed to load products");
+    } finally {
+      setLoading(false);
+    }
+  }, [memoizedProductIds, endpoint, mode, limit]);
+
+  useEffect(() => {
+    // Always fetch - either specific products or list all products
+    fetchProducts();
+  }, [fetchProducts]);
+
+  return {
+    products,
+    loading,
+    error,
+    refetch: fetchProducts,
+  };
+}

package/src/hooks/useProductPage.ts

@@ -0,0 +1,467 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import {
+  useProduct,
+  useProductOptional,
+  useDesignOptional,
+  type ReactProductContext,
+  type Artwork,
+  type PlacementDesign,
+  type ClipShape,
+} from "../patterns/Product";
+import {
+  useShop,
+  useShopOptional,
+  type ShopContextValue,
+} from "../patterns/ShopProvider";
+import {
+  useRealtimeOptional,
+  type RealtimeContextValue,
+} from "../patterns/RealtimeProvider";
+import {
+  useMockupPriorityOptional,
+  type MockupPriorityContextValue,
+} from "../patterns/MockupPriorityProvider";
+import type { CatalogProduct, OptionSelection, ImageAlignment } from "@snowcone-app/sdk";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// PROVIDER STATUS - For helpful error messages
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export interface ProviderStatus {
+  hasShop: boolean;
+  hasProduct: boolean;
+  hasRealtime: boolean;
+  hasPriority: boolean;
+  hasArtwork: boolean;
+  missing: string[];
+}
+
+/**
+ * Check which providers are available in the current context.
+ * Useful for debugging and conditional rendering.
+ */
+export function useProviderStatus(): ProviderStatus {
+  const shop = useShopOptional();
+  const product = useProductOptional();
+  const design = useDesignOptional();
+  const realtime = useRealtimeOptional();
+  const priority = useMockupPriorityOptional();
+
+  const missing: string[] = [];
+  if (!shop) missing.push("Shop");
+  if (!product) missing.push("Product");
+  if (!realtime) missing.push("RealtimeProvider");
+  if (!priority) missing.push("MockupPriorityProvider");
+  if (!design?.selectedArtwork) missing.push("ArtSelector or selectedArtwork");
+
+  return {
+    hasShop: !!shop,
+    hasProduct: !!product,
+    hasRealtime: !!realtime,
+    hasPriority: !!priority,
+    hasArtwork: !!design?.selectedArtwork,
+    missing,
+  };
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// PRODUCT PAGE CONTEXT - Unified interface
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export interface ProductPageContext {
+  // ── Product Data ──────────────────────────────────────────────────────────
+  /** The product being displayed */
+  product: CatalogProduct | undefined;
+  /** Whether product data is loading */
+  isLoading: boolean;
+  /** Current variant selection (size, color, etc.) */
+  selection: OptionSelection;
+  /** Update variant selection */
+  updateSelection: (selection: OptionSelection) => void;
+  /** Current price based on selection */
+  currentPrice: number | undefined;
+
+  // ── Artwork & Design ──────────────────────────────────────────────────────
+  /** Currently selected artwork */
+  selectedArtwork: Artwork | undefined;
+  /** Set the selected artwork */
+  setSelectedArtwork: (artwork: Artwork | undefined) => void;
+  /** All available artworks */
+  artworks: Artwork[];
+  /** Add an artwork to the collection */
+  addArtwork: (artwork: Artwork) => void;
+  /** Placement designs for current product */
+  placements: Record<string, PlacementDesign>;
+  /** Currently selected placement */
+  selectedPlacement: string | undefined;
+  /** Set selected placement */
+  setSelectedPlacement: (placement: string) => void;
+
+  // ── Design Methods ────────────────────────────────────────────────────────
+  /** Update a placement's design */
+  setPlacementDesign: (placement: string, design: Partial<PlacementDesign>) => void;
+  /** Get a placement's design */
+  getPlacementDesign: (placement: string) => PlacementDesign | undefined;
+  /** Apply artwork to a specific placement */
+  applyArtworkToPlacement: (placement: string, artwork?: Artwork) => void;
+  /** Set clip shape for a placement */
+  setPlacementClipShape: (placement: string, clipShape: ClipShape) => void;
+  /** Get clip shape for a placement */
+  getPlacementClipShape: (placement: string) => ClipShape;
+
+  // ── Realtime (Optional) ───────────────────────────────────────────────────
+  /** Realtime mockup context (if RealtimeProvider is present) */
+  realtime: RealtimeContextValue | undefined;
+  /** Whether realtime mockups are available */
+  hasRealtime: boolean;
+
+  // ── Priority (Optional) ───────────────────────────────────────────────────
+  /** Priority context (if MockupPriorityProvider is present) */
+  priority: MockupPriorityContextValue | undefined;
+  /** Whether priority system is available */
+  hasPriority: boolean;
+
+  // ── Shop ──────────────────────────────────────────────────────────────────
+  /** Queue an image update (throttled) */
+  queueImageUpdate: ShopContextValue["queueImageUpdate"];
+  /** Cancel a queued image update */
+  cancelImageUpdate: ShopContextValue["cancelImageUpdate"];
+  /** Get cached product data */
+  getCachedProduct: (productId: string) => CatalogProduct | undefined;
+
+  // ── Provider Status ───────────────────────────────────────────────────────
+  /** Check which providers are available */
+  providers: ProviderStatus;
+}
+
+/**
+ * useProductPage - Unified hook for building product pages
+ *
+ * Combines all necessary contexts (Product, Shop, Realtime, Priority) into
+ * a single, easy-to-use interface. This is the recommended way to access
+ * context in custom product page components.
+ *
+ * **Requirements:**
+ * - Must be used within a `<Shop>` provider
+ * - Must be used within a `<Product>` provider
+ * - RealtimeProvider and MockupPriorityProvider are optional
+ *
+ * @example
+ * ```tsx
+ * function MyProductPage() {
+ *   const {
+ *     product,
+ *     selection,
+ *     updateSelection,
+ *     selectedArtwork,
+ *     setSelectedArtwork,
+ *     placements,
+ *     realtime,
+ *   } = useProductPage();
+ *
+ *   if (!product) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{product.name}</h1>
+ *       <button onClick={() => setSelectedArtwork(myArtwork)}>
+ *         Set Artwork
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @throws Error if used outside of Shop or Product context
+ */
+export function useProductPage(): ProductPageContext {
+  const shop = useShop(); // Required - will throw if missing
+  const productCtx = useProduct(); // Required - will throw if missing
+  const realtime = useRealtimeOptional();
+  const priority = useMockupPriorityOptional();
+
+  const providers = useProviderStatus();
+
+  return useMemo(
+    () => ({
+      // Product Data
+      product: productCtx.product,
+      isLoading: productCtx.loading ?? false,
+      selection: productCtx.selection ?? {},
+      updateSelection: productCtx.updateSelection ?? (() => {}),
+      currentPrice: productCtx.currentPrice,
+
+      // Artwork & Design
+      selectedArtwork: productCtx.selectedArtwork,
+      setSelectedArtwork: productCtx.setSelectedArtwork,
+      artworks: shop.artworks,
+      addArtwork: shop.addArtwork,
+      placements: productCtx.placements,
+      selectedPlacement: productCtx.selectedPlacement,
+      setSelectedPlacement: productCtx.setSelectedPlacement,
+
+      // Design Methods
+      setPlacementDesign: productCtx.setPlacementDesign,
+      getPlacementDesign: productCtx.getPlacementDesign,
+      applyArtworkToPlacement: productCtx.applyArtworkToPlacement,
+      setPlacementClipShape: productCtx.setPlacementClipShape,
+      getPlacementClipShape: productCtx.getPlacementClipShape,
+
+      // Realtime
+      realtime,
+      hasRealtime: !!realtime,
+
+      // Priority
+      priority,
+      hasPriority: !!priority,
+
+      // Shop
+      queueImageUpdate: shop.queueImageUpdate,
+      cancelImageUpdate: shop.cancelImageUpdate,
+      getCachedProduct: shop.getProduct,
+
+      // Provider Status
+      providers,
+    }),
+    [productCtx, shop, realtime, priority, providers]
+  );
+}
+
+/**
+ * useProductPageOptional - Like useProductPage but returns undefined if contexts missing
+ *
+ * Use this when you're not sure if you're inside the required providers.
+ * Returns undefined instead of throwing an error.
+ *
+ * @example
+ * ```tsx
+ * function MaybeProductComponent() {
+ *   const page = useProductPageOptional();
+ *
+ *   if (!page) {
+ *     return <div>Not inside a product page</div>;
+ *   }
+ *
+ *   return <div>{page.product?.name}</div>;
+ * }
+ * ```
+ */
+export function useProductPageOptional(): ProductPageContext | undefined {
+  const shop = useShopOptional();
+  const productCtx = useProductOptional();
+  const realtime = useRealtimeOptional();
+  const priority = useMockupPriorityOptional();
+
+  const providers = useProviderStatus();
+
+  if (!shop || !productCtx) {
+    return undefined;
+  }
+
+  return {
+    // Product Data
+    product: productCtx.product,
+    isLoading: productCtx.loading ?? false,
+    selection: productCtx.selection ?? {},
+    updateSelection: productCtx.updateSelection ?? (() => {}),
+    currentPrice: productCtx.currentPrice,
+
+    // Artwork & Design
+    selectedArtwork: productCtx.selectedArtwork,
+    setSelectedArtwork: productCtx.setSelectedArtwork,
+    artworks: shop.artworks,
+    addArtwork: shop.addArtwork,
+    placements: productCtx.placements,
+    selectedPlacement: productCtx.selectedPlacement,
+    setSelectedPlacement: productCtx.setSelectedPlacement,
+
+    // Design Methods
+    setPlacementDesign: productCtx.setPlacementDesign,
+    getPlacementDesign: productCtx.getPlacementDesign,
+    applyArtworkToPlacement: productCtx.applyArtworkToPlacement,
+    setPlacementClipShape: productCtx.setPlacementClipShape,
+    getPlacementClipShape: productCtx.getPlacementClipShape,
+
+    // Realtime
+    realtime,
+    hasRealtime: !!realtime,
+
+    // Priority
+    priority,
+    hasPriority: !!priority,
+
+    // Shop
+    queueImageUpdate: shop.queueImageUpdate,
+    cancelImageUpdate: shop.cancelImageUpdate,
+    getCachedProduct: shop.getProduct,
+
+    // Provider Status
+    providers,
+  };
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// PROJECTION HOOKS - Simplified access to nested state
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * useCurrentPlacements - Get placements for the current product
+ *
+ * Simplified access to placement data without dealing with nested state.
+ *
+ * @example
+ * ```tsx
+ * const placements = useCurrentPlacements();
+ * // { front: { imageUrl: '...', alignment: {...} }, back: {...} }
+ * ```
+ */
+export function useCurrentPlacements(): Record<string, PlacementDesign> {
+  const productCtx = useProductOptional();
+  return productCtx?.placements ?? {};
+}
+
+/**
+ * useArtworkAlignment - Get alignment for a specific artwork on a placement
+ *
+ * @param placement - The placement name (e.g., "front", "back")
+ * @returns The alignment or undefined
+ *
+ * @example
+ * ```tsx
+ * const alignment = useArtworkAlignment("front");
+ * // { x: 0.5, y: 0.5, scale: 1, rotation: 0 }
+ * ```
+ */
+export function useArtworkAlignment(
+  placement: string
+): ImageAlignment | undefined {
+  const productCtx = useProductOptional();
+  return productCtx?.placements[placement]?.alignment;
+}
+
+/**
+ * useSetArtworkAlignment - Set alignment for a placement
+ *
+ * @returns A function to update alignment
+ *
+ * @example
+ * ```tsx
+ * const setAlignment = useSetArtworkAlignment();
+ * setAlignment("front", "center");
+ * setAlignment("back", "top");
+ * ```
+ */
+export function useSetArtworkAlignment(): (
+  placement: string,
+  alignment: ImageAlignment
+) => void {
+  const productCtx = useProductOptional();
+
+  return useCallback(
+    (placement: string, alignment: ImageAlignment) => {
+      if (productCtx) {
+        const currentDesign = productCtx.placements[placement];
+        productCtx.setPlacementDesign(placement, {
+          ...currentDesign,
+          alignment,
+        });
+      }
+    },
+    [productCtx]
+  );
+}
+
+/**
+ * useSelectedArtwork - Get and set the selected artwork
+ *
+ * A simplified hook for artwork selection.
+ *
+ * @example
+ * ```tsx
+ * const [artwork, setArtwork] = useSelectedArtwork();
+ *
+ * return (
+ *   <button onClick={() => setArtwork({ type: 'regular', src: url })}>
+ *     Select Artwork
+ *   </button>
+ * );
+ * ```
+ */
+export function useSelectedArtwork(): [
+  Artwork | undefined,
+  (artwork: Artwork | undefined) => void
+] {
+  const productCtx = useProductOptional();
+  const shopCtx = useShopOptional();
+
+  // Prefer product context, fall back to shop context
+  const ctx = productCtx || shopCtx;
+
+  const setArtwork = useCallback(
+    (artwork: Artwork | undefined) => {
+      ctx?.setSelectedArtwork(artwork);
+    },
+    [ctx]
+  );
+
+  return [ctx?.selectedArtwork, setArtwork];
+}
+
+/**
+ * useProductSelection - Get and set variant selection
+ *
+ * @example
+ * ```tsx
+ * const [selection, updateSelection] = useProductSelection();
+ *
+ * return (
+ *   <button onClick={() => updateSelection({ ...selection, size: 'L' })}>
+ *     Large
+ *   </button>
+ * );
+ * ```
+ */
+export function useProductSelection(): [
+  OptionSelection,
+  (selection: OptionSelection) => void
+] {
+  const productCtx = useProductOptional();
+
+  const update = useCallback(
+    (selection: OptionSelection) => {
+      productCtx?.updateSelection?.(selection);
+    },
+    [productCtx]
+  );
+
+  return [productCtx?.selection ?? {}, update];
+}
+
+/**
+ * usePlacementClipShape - Get and set clip shape for a placement
+ *
+ * @example
+ * ```tsx
+ * const [clipShape, setClipShape] = usePlacementClipShape("front");
+ * // clipShape: 'rectangle' | 'circle' | 'custom'
+ * ```
+ */
+export function usePlacementClipShape(
+  placement: string
+): [ClipShape, (shape: ClipShape) => void] {
+  const productCtx = useProductOptional();
+
+  const setShape = useCallback(
+    (shape: ClipShape) => {
+      productCtx?.setPlacementClipShape(placement, shape);
+    },
+    [productCtx, placement]
+  );
+
+  return [
+    productCtx?.getPlacementClipShape(placement) ?? "rectangle",
+    setShape,
+  ];
+}