@snowcone-app/ui 0.1.43 → 0.2.0

package/src/patterns/ProductPageProvider.tsx

@@ -0,0 +1,224 @@
+"use client";
+
+import React, { type ReactNode } from "react";
+import { Shop, type ShopProps } from "./ShopProvider";
+import { Product, type ProductProviderProps } from "./Product";
+import { RealtimeProvider, type RealtimeProviderProps } from "./RealtimeProvider";
+import { MockupPriorityProvider } from "./MockupPriorityProvider";
+import type { Artwork } from "./Product";
+
+/**
+ * ProductPageProvider - Quick-start provider for product pages
+ *
+ * A convenience wrapper that sets up the complete provider stack needed for
+ * a fully-featured product page. Use this instead of manually nesting
+ * Shop > RealtimeProvider > MockupPriorityProvider > Product.
+ *
+ * **This provider includes:**
+ * - `Shop` - Global artwork state and image throttling
+ * - `RealtimeProvider` - Live mockup updates (optional, enabled by default)
+ * - `MockupPriorityProvider` - Priority-based mockup rendering
+ * - `Product` - Product data and variant selection
+ *
+ * **Minimal setup:**
+ * ```tsx
+ * <ProductPageProvider productId="shirt-123">
+ *   <ArtSelector artworks={[...]} />
+ *   <ProductImage />
+ *   <ProductOptions />
+ *   <AddToCart />
+ * </ProductPageProvider>
+ * ```
+ *
+ * **With configuration:**
+ * ```tsx
+ * <ProductPageProvider
+ *   productId="shirt-123"
+ *   initialArtwork={{ type: 'regular', src: 'https://...' }}
+ *   enableRealtime={true}
+ *   mockupUrl="https://api.example.com"
+ * >
+ *   <MyProductPage />
+ * </ProductPageProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complete product detail page
+ * function ProductDetailPage({ productId }: { productId: string }) {
+ *   return (
+ *     <ProductPageProvider productId={productId}>
+ *       <div className="grid md:grid-cols-2 gap-8">
+ *         <ProductImage />
+ *         <div>
+ *           <ProductName />
+ *           <ProductPrice />
+ *           <ArtSelector artworks={artworkOptions} />
+ *           <ProductOptions />
+ *           <AddToCart onClick={handleAddToCart} />
+ *         </div>
+ *       </div>
+ *     </ProductPageProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using the useProductPage hook inside
+ * function MyCustomComponent() {
+ *   const {
+ *     product,
+ *     selection,
+ *     selectedArtwork,
+ *     realtime,
+ *     providers,
+ *   } = useProductPage();
+ *
+ *   return <div>{product?.name}</div>;
+ * }
+ *
+ * <ProductPageProvider productId="shirt-123">
+ *   <MyCustomComponent />
+ * </ProductPageProvider>
+ * ```
+ */
+export interface ProductPageProviderProps {
+  children: ReactNode;
+
+  // ── Product Configuration ──────────────────────────────────────────────────
+  /** Product ID to load */
+  productId: string;
+  /** Pre-loaded product data (skips fetch) */
+  productData?: ProductProviderProps["productData"];
+
+  // ── Shop Configuration ─────────────────────────────────────────────────────
+  /** API endpoint for product data */
+  endpoint?: string;
+  /** Mockup generation URL */
+  mockupUrl?: string;
+  /** Your public Shop ID (same value as `&shop=` in mockup/buy URLs) */
+  shop?: string;
+  /** Initial artwork to select (avoids layout shift) */
+  initialArtwork?: Artwork;
+
+  // ── Realtime Configuration ─────────────────────────────────────────────────
+  /** Enable realtime mockups (default: true) */
+  enableRealtime?: boolean;
+  /** WebSocket URL for realtime mockups */
+  realtimeWsUrl?: string;
+  /**
+   * Endpoint that issues a realtime session grant (POST { shopId } →
+   * { token, expiresAt }). With this set, realtime authorizes via a renewable
+   * token billed to the shop (the `shop` prop, = shop.id); without it the
+   * legacy seal runs.
+   */
+  realtimeGrantUrl?: string;
+
+  // ── Priority Configuration ─────────────────────────────────────────────────
+  /** Enable priority-based mockup rendering (default: true) */
+  enablePriority?: boolean;
+}
+
+export function ProductPageProvider({
+  children,
+  productId,
+  productData,
+  endpoint,
+  mockupUrl,
+  shop,
+  initialArtwork,
+  enableRealtime = true,
+  realtimeWsUrl,
+  realtimeGrantUrl,
+  enablePriority = true,
+}: ProductPageProviderProps) {
+  // Build the provider tree
+  let content = (
+    <Product productId={productId} productData={productData}>
+      {children}
+    </Product>
+  );
+
+  // Wrap with MockupPriorityProvider if enabled
+  if (enablePriority) {
+    content = <MockupPriorityProvider>{content}</MockupPriorityProvider>;
+  }
+
+  // Wrap with RealtimeProvider if enabled
+  if (enableRealtime) {
+    content = (
+      <RealtimeProvider
+        wsUrl={realtimeWsUrl}
+        shop={shop}
+        grantUrl={realtimeGrantUrl}
+      >
+        {content}
+      </RealtimeProvider>
+    );
+  }
+
+  // Always wrap with Shop (required for artwork management)
+  return (
+    <Shop
+      endpoint={endpoint}
+      mockupUrl={mockupUrl}
+      shop={shop}
+      initialArtwork={initialArtwork}
+    >
+      {content}
+    </Shop>
+  );
+}
+
+/**
+ * ProductPageProviderMinimal - Lightweight provider for simple use cases
+ *
+ * A minimal provider that only includes Shop and Product contexts.
+ * Use this when you don't need realtime mockups or priority rendering.
+ *
+ * **Use cases:**
+ * - Product listing pages (no live editing)
+ * - Simple product cards
+ * - Static mockup display
+ *
+ * @example
+ * ```tsx
+ * <ProductPageProviderMinimal productId="shirt-123">
+ *   <ProductImage />
+ *   <ProductPrice />
+ * </ProductPageProviderMinimal>
+ * ```
+ */
+export interface ProductPageProviderMinimalProps {
+  children: ReactNode;
+  productId: string;
+  productData?: ProductProviderProps["productData"];
+  endpoint?: string;
+  mockupUrl?: string;
+  shop?: string;
+  initialArtwork?: Artwork;
+}
+
+export function ProductPageProviderMinimal({
+  children,
+  productId,
+  productData,
+  endpoint,
+  mockupUrl,
+  shop,
+  initialArtwork,
+}: ProductPageProviderMinimalProps) {
+  return (
+    <Shop
+      endpoint={endpoint}
+      mockupUrl={mockupUrl}
+      shop={shop}
+      initialArtwork={initialArtwork}
+    >
+      <Product productId={productId} productData={productData}>
+        {children}
+      </Product>
+    </Shop>
+  );
+}