@snowcone-app/ui 0.1.43 → 0.2.1

package/src/composed/ProductCard.tsx

@@ -0,0 +1,298 @@
+import React from "react";
+import { useProduct } from "../patterns/Product";
+import { ProductImage } from "./ProductImage";
+import { ProductPrice } from "../primitives/ProductPrice";
+
+export interface ProductCardProps {
+  /**
+   * Click handler for the card
+   */
+  onClick?: () => void;
+
+  /**
+   * Additional CSS classes for the card container
+   */
+  className?: string;
+
+  /**
+   * Card variant - determines the layout and styling
+   */
+  variant?: "default" | "overlay" | "minimal";
+
+  /**
+   * Whether to show the product price
+   */
+  showPrice?: boolean;
+
+  /**
+   * Whether to show the product category/tag
+   */
+  showCategory?: boolean;
+
+  /**
+   * Children to render inside the card (for custom content)
+   */
+  children?: React.ReactNode;
+
+  /**
+   * The mockup image URL to render. Build it with
+   * `getMockupUrl(asset, productCode, { shop })` (ADR-0075) and pass it in.
+   * `null`/omitted shows a loading shimmer.
+   */
+  src?: string | null;
+}
+
+const GRADIENT_SCRIM =
+  "linear-gradient(to top, black 0%, rgba(0, 0, 0, 0.738) 19%, rgba(0, 0, 0, 0.541) 34%, rgba(0, 0, 0, 0.382) 47%, rgba(0, 0, 0, 0.278) 56.5%, rgba(0, 0, 0, 0.194) 65%, rgba(0, 0, 0, 0.126) 73%, rgba(0, 0, 0, 0.075) 80.2%, rgba(0, 0, 0, 0.042) 86.1%, rgba(0, 0, 0, 0.021) 91%, rgba(0, 0, 0, 0.008) 95.2%, rgba(0, 0, 0, 0.002) 98.2%, transparent 100%)";
+
+/**
+ * ProductCard - Display product with image, name, price, and category
+ *
+ * A composed component that renders a product card with multiple layout variants.
+ * Integrates with Product context for automatic data binding and supports
+ * clickable cards for navigation.
+ *
+ * Features:
+ * - Three distinct variants (default, overlay, minimal)
+ * - Optional artwork display via ProductImage
+ * - Automatic price formatting
+ * - Category/tag display
+ * - Clickable card with accessible button semantics
+ * - Gradient overlay for text visibility (overlay variant)
+ * - Responsive aspect ratios
+ * - Dark mode support
+ * - CSS custom property theming
+ *
+ * **Variants:**
+ * - `default` - Card with padding, rounded corners, and hover shadow
+ * - `overlay` - Image with gradient overlay and text at bottom (search results style)
+ * - `minimal` - Clean layout with image and text below (product grid style)
+ *
+ * **Context Integration:**
+ * - Must be used within a `Product` context provider
+ * - Automatically extracts product name, price, category from context
+ * - ProductImage inside ProductCard reads artwork from Design context (set by ArtSelector)
+ * - Works seamlessly with `ProductList` for catalog display
+ *
+ * @example
+ * ```tsx
+ * // In a product catalog with ProductList
+ * <ProductList limit={6}>
+ *   <ProductCard
+ *     variant="overlay"
+ *     showCategory={true}
+ *     onClick={() => router.push('/product/${product.id}')}
+ *   />
+ * </ProductList>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Standalone with explicit Product context and artwork via ArtSelector
+ * <Product productId="shirt-123">
+ *   <ArtSelector artworks={[...]} />
+ *   <ProductCard
+ *     showPrice={true}
+ *     variant="minimal"
+ *   />
+ * </Product>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom children for badges or actions
+ * <ProductCard variant="default" showPrice>
+ *   <div className="mt-2">
+ *     <span className="badge">New</span>
+ *     <button className="add-to-cart-btn">Quick Add</button>
+ *   </div>
+ * </ProductCard>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Grid layout example
+ * <div className="grid grid-cols-3 gap-4">
+ *   {products.map(product => (
+ *     <Product key={product.id} productData={product}>
+ *       <ProductCard variant="minimal" showPrice />
+ *     </Product>
+ *   ))}
+ * </div>
+ * ```
+ *
+ * @param onClick - Click handler (makes card interactive/clickable)
+ * @param className - Additional CSS classes for card container
+ * @param variant - Layout variant ("default", "overlay", or "minimal")
+ * @param showPrice - Display product price (default: false)
+ * @param showCategory - Display product category/tag (default: true)
+ * @param children - Custom content to render inside card (badges, buttons, etc.)
+ */
+export function ProductCard({
+  onClick,
+  className = "",
+  variant = "default",
+  showPrice = false,
+  showCategory = true,
+  children,
+  src = null,
+}: ProductCardProps) {
+  const { product } = useProduct();
+
+  if (!product) {
+    return null;
+  }
+
+  const category = product.tags?.[0] || "Product";
+  const productName = product.name || "Unnamed Product";
+
+  // Determine wrapper element and props
+  const WrapperElement = onClick ? "button" : "div";
+  const wrapperProps = onClick
+    ? {
+        onClick,
+        className: `${className} cursor-pointer text-left`,
+        "aria-label": `View ${category} ${productName}`,
+      }
+    : {
+        className,
+      };
+
+  // Variant: Overlay (like search results)
+  if (variant === "overlay") {
+    // Check if className includes rounded-none to disable border radius
+    const hasRoundedNone = className?.includes("rounded-none");
+
+    return (
+      <WrapperElement
+        {...wrapperProps}
+        className={`w-full bg-background relative group text-left block ${onClick ? "cursor-pointer" : ""} ${className}`}
+        style={{ margin: 0, padding: 0, border: 0, lineHeight: 0 }}
+      >
+        <div
+          className={`w-full aspect-2/3 bg-muted relative overflow-hidden hover:bg-muted/80 transition-colors ${hasRoundedNone ? "" : "rounded-image"}`}
+        >
+          <ProductImage
+            src={src}
+            alt={productName}
+            className={`absolute inset-0 w-full h-full object-cover block ${hasRoundedNone ? "rounded-none" : "rounded-image"}`}
+          />
+
+          {/* Subtle border overlay - right and bottom only for grid layouts */}
+          <div
+            className="absolute inset-0 pointer-events-none"
+            style={{
+              boxShadow: 'inset -1px -1px 0 0 rgba(0, 0, 0, 0.1)',
+            }}
+            aria-hidden="true"
+          />
+
+          {/* Gradient overlay */}
+          <div
+            className="absolute left-0 right-0 bottom-0 pointer-events-none"
+            style={{
+              height: "60%",
+              background: GRADIENT_SCRIM,
+              opacity: 0.85,
+              zIndex: 10,
+            }}
+            aria-hidden="true"
+          />
+
+          {/* Product info overlay */}
+          <div
+            className="absolute bottom-0 left-0 right-0 p-4 pb-2 z-20 pointer-events-none"
+            aria-hidden="true"
+          >
+            <div className="text-sm text-white font-heading">
+              {showCategory && (
+                <div className="text-xs font-caption" style={{ color: 'rgba(255, 255, 255, 0.7)' }}>
+                  {category}
+                </div>
+              )}
+              {productName}
+            </div>
+          </div>
+        </div>
+        {children}
+      </WrapperElement>
+    );
+  }
+
+  // Variant: Minimal (image fills space, text below)
+  if (variant === "minimal") {
+    // Check if className includes rounded-none to disable border radius
+    const hasRoundedNone = className?.includes("rounded-none");
+
+    return (
+      <WrapperElement
+        {...wrapperProps}
+        className={`w-full bg-background relative group text-left ${onClick ? "cursor-pointer" : ""} ${className}`}
+        style={{ margin: 0, padding: 0, border: 0 }}
+      >
+        <div className="flex flex-col">
+          <div
+            className={`w-full aspect-2/3 bg-muted relative overflow-hidden hover:bg-muted/80 transition-colors ${hasRoundedNone ? "" : "rounded-image"}`}
+          >
+            <ProductImage
+              src={src}
+              alt={productName}
+              className={`absolute inset-0 w-full h-full object-cover block ${hasRoundedNone ? "rounded-none" : "rounded-image"}`}
+            />
+
+            {/* Subtle border overlay - right and bottom only for grid layouts */}
+            <div
+              className="absolute inset-0 pointer-events-none"
+              style={{
+                boxShadow: 'inset -1px -1px 0 0 rgba(0, 0, 0, 0.1)',
+              }}
+              aria-hidden="true"
+            />
+          </div>
+
+          {/* Product info below image */}
+          <div className="p-3">
+            {showCategory && (
+              <div className="text-xs text-muted-foreground mb-1 font-caption">
+                {category}
+              </div>
+            )}
+            <h3 className="font-heading text-sm mb-1 line-clamp-2">
+              {productName}
+            </h3>
+            {showPrice && (
+              <ProductPrice className="text-base text-primary" />
+            )}
+          </div>
+        </div>
+        {children}
+      </WrapperElement>
+    );
+  }
+
+  // Variant: Default (card with padding)
+  return (
+    <WrapperElement
+      {...wrapperProps}
+      className={`p-4 bg-card text-foreground rounded-card ${onClick ? "hover:shadow-lg transition-shadow cursor-pointer" : ""} ${className}`}
+    >
+      <div className="aspect-2/3 bg-muted rounded-image overflow-hidden mb-3 relative">
+        <ProductImage
+          src={src}
+          alt={productName}
+          className="absolute inset-0 w-full h-full object-cover rounded-image"
+        />
+      </div>
+      <h3 className="font-heading text-sm mb-2 line-clamp-2">
+        {productName}
+      </h3>
+      {showCategory && (
+        <div className="text-xs text-muted-foreground mb-2 font-caption">{category}</div>
+      )}
+      {showPrice && (
+        <ProductPrice className="text-base text-primary" />
+      )}
+      {children}
+    </WrapperElement>
+  );
+}

package/src/composed/ProductGallery.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import type { CatalogProduct } from "@snowcone-app/sdk";
+import {
+  useProductGallery,
+  type UseProductGalleryOptions,
+} from "../hooks/useProductGallery";
+
+export interface ProductGalleryProps extends UseProductGalleryOptions {
+  productIds?: string[]; // Make optional - when empty/undefined, lists all products
+  children: (
+    products: CatalogProduct[],
+    loading: boolean,
+    error: string | null,
+    refetch: () => void
+  ) => React.ReactNode;
+}
+
+/**
+ * ProductGallery - Fetch products and provide them via render prop
+ *
+ * Two modes:
+ * 1. Specific products: Pass productIds array
+ * 2. List all products: Pass empty array or omit productIds
+ *
+ * @example Specific products
+ * <ProductGallery productIds={["BEEB77", "AR2P3G", "KMYKUK"]}>
+ *   {(products, loading, error) => (
+ *     <div className="grid grid-cols-3 gap-4">
+ *       {products.map(product => (
+ *         <ProductImage key={product.id} product={product} />
+ *       ))}
+ *     </div>
+ *   )}
+ * </ProductGallery>
+ *
+ * @example List all products
+ * <ProductGallery limit={12}>
+ *   {(products, loading, error) => (
+ *     <ProductCatalog products={products} />
+ *   )}
+ * </ProductGallery>
+ */
+export function ProductGallery({
+  productIds = [], // Default to empty array for listing all products
+  children,
+  ...options
+}: ProductGalleryProps) {
+  const { products, loading, error, refetch } = useProductGallery(
+    productIds,
+    options
+  );
+
+  return <>{children(products, loading, error, refetch)}</>;
+}

package/src/composed/ProductImage.tsx

@@ -0,0 +1,129 @@
+"use client";
+
+import React, { useState, useEffect, memo } from "react";
+import type { AspectRatio } from "@snowcone-app/sdk";
+
+/**
+ * Artwork shape types. Kept here for backwards-compatible imports
+ * (`import type { RegularArtwork } from "./ProductImage"`); the canonical
+ * definitions also live in `patterns/Product`.
+ */
+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;
+
+export type { AspectRatio };
+
+/**
+ * ProductImage — a thin `<img>` renderer for a mockup URL.
+ *
+ * Since ADR-0075 (the image-CDN model), a mockup is a **public URL** you build
+ * yourself (e.g. with `getMockupUrl(asset, productCode, { shop })`) and pass in
+ * as `src`. This component no longer builds URLs, talks to any context, signs,
+ * or queues renders — it only renders, with the loading / fade-in / error
+ * niceties you want around a remote image.
+ *
+ * @example
+ * ```tsx
+ * import { getMockupUrl } from "@snowcone-app/sdk";
+ * import { ProductImage } from "@snowcone-app/ui";
+ *
+ * const src = getMockupUrl(artworkUrl, "hoodie-black", { shop: shopId });
+ * <ProductImage src={src} alt="Black hoodie with my art" />
+ * ```
+ *
+ * - `src={null}` → loading shimmer (the URL isn't ready yet).
+ * - image fades in on load.
+ * - `onError` → a quiet error state.
+ */
+export interface ProductImageProps {
+  /** The mockup image URL. `null` shows a loading shimmer. */
+  src: string | null;
+  /** Additional CSS classes for the wrapper. */
+  className?: string;
+  /** Accessible alt text. */
+  alt?: string;
+  /** Optional intrinsic width hint passed to the `<img>`. */
+  width?: number;
+}
+
+export const ProductImage = memo(function ProductImage({
+  src,
+  className,
+  alt = "Product preview",
+  width,
+}: ProductImageProps) {
+  const [loaded, setLoaded] = useState(false);
+  const [errored, setErrored] = useState(false);
+
+  // Reset transition state whenever the source changes.
+  useEffect(() => {
+    setLoaded(false);
+    setErrored(false);
+  }, [src]);
+
+  const wrapperClassName = `relative overflow-hidden ${className || ""}`.trim();
+  const showShimmer = src === null || (!loaded && !errored);
+
+  return (
+    <div className={wrapperClassName}>
+      {showShimmer && (
+        <>
+          <div
+            className="absolute inset-0 z-10"
+            style={{
+              background:
+                "linear-gradient(90deg, var(--color-muted, #e0e0e0) 25%, var(--color-background, #f5f5f5) 37%, var(--color-muted, #e0e0e0) 63%)",
+              backgroundSize: "400% 100%",
+              animation: "shimmer 1.2s ease-in-out infinite",
+            }}
+            role="progressbar"
+            aria-label={`Loading ${alt}`}
+            aria-valuemin={0}
+            aria-valuemax={100}
+          />
+          <style>{`
+            @keyframes shimmer {
+              0% { background-position: 100% 50%; }
+              100% { background-position: 0% 50%; }
+            }
+          `}</style>
+        </>
+      )}
+
+      {errored && (
+        <div
+          className="absolute inset-0 flex items-center justify-center bg-muted"
+          role="alert"
+          aria-live="assertive"
+        >
+          <p className="text-red-500 text-sm">Failed to load image</p>
+        </div>
+      )}
+
+      {src !== null && !errored && (
+        <img
+          alt={alt}
+          width={width}
+          crossOrigin="anonymous"
+          loading="lazy"
+          className={`w-full h-full object-cover transition-opacity duration-300 ${
+            loaded ? "opacity-100" : "opacity-0"
+          }`}
+          src={src}
+          onLoad={() => setLoaded(true)}
+          onError={() => setErrored(true)}
+        />
+      )}
+    </div>
+  );
+});

package/src/composed/ProductList.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import React, { useState, useEffect } from "react";
+import { Product } from "../patterns/Product";
+import { useShopOptional } from "../patterns/ShopProvider";
+import { listProducts } from "@snowcone-app/sdk";
+import type { CatalogProduct } from "@snowcone-app/sdk";
+import { readEnv } from "../lib/env";
+
+export interface ProductListProps {
+  endpoint?: string;
+  limit?: number;
+  children: React.ReactNode;
+  /**
+   * Additional CSS classes for the grid container
+   */
+  className?: string;
+  /**
+   * Grid column classes (Tailwind responsive grid)
+   */
+  gridClassName?: string;
+}
+
+/**
+ * ProductList - Fetch and display a grid of products
+ *
+ * A composed component that efficiently fetches multiple products in a single
+ * API call and renders them in a responsive grid. Pre-fetches product data to
+ * avoid duplicate API calls from child Product components.
+ *
+ * Features:
+ * - Single API call for multiple products (efficient)
+ * - Pre-fetched data passed to Product components
+ * - Responsive grid layout (1/2/3 columns)
+ * - Loading state with placeholder
+ * - Integration with Shop context for configuration
+ * - Automatic endpoint inheritance from Shop context
+ * - Customizable limit
+ *
+ * **Performance:**
+ * - Fetches all products once (not per-product)
+ * - Passes productData to Product to skip individual fetches
+ * - Reduces API calls from N to 1
+ *
+ * **Context Integration:**
+ * - Works with Shop context for endpoint configuration
+ * - Falls back to props or environment variables
+ * - Each child Product gets pre-fetched data
+ *
+ * @example
+ * ```tsx
+ * // Basic product grid
+ * <ProductList limit={12}>
+ *   <ProductCard variant="minimal" showPrice />
+ * </ProductList>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Shop context
+ * <Shop endpoint="http://localhost:3000">
+ *   <ProductList limit={6}>
+ *     <ProductCard variant="overlay" showCategory />
+ *   </ProductList>
+ * </Shop>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom children per product
+ * <ProductList limit={8}>
+ *   <div className="space-y-2">
+ *     <ProductImage />
+ *     <ProductCard variant="minimal" />
+ *     <AddToCart className="w-full" />
+ *   </div>
+ * </ProductList>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Standalone with explicit configuration
+ * <ProductList
+ *   endpoint="http://localhost:3000"
+ *   limit={20}
+ * >
+ *   <ProductCard showPrice showCategory />
+ * </ProductList>
+ * ```
+ *
+ * @param endpoint - API endpoint URL (falls back to Shop context or env)
+ * @param limit - Maximum number of products to fetch (default: 10)
+ * @param children - Component(s) to render for each product (receives Product context)
+ */
+export function ProductList({
+  endpoint,
+  limit = 10,
+  children,
+  className = "",
+  gridClassName = "grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6",
+}: ProductListProps) {
+  const [products, setProducts] = useState<CatalogProduct[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  // Get Shop context for configuration
+  const shopContext = useShopOptional();
+
+  // Use shop context values if available, otherwise use props or environment defaults
+  const effectiveEndpoint = endpoint ?? shopContext?.endpoint ?? readEnv("NEXT_PUBLIC_MERCH_ENDPOINT");
+
+  useEffect(() => {
+    async function fetchProducts() {
+      try {
+        const response = await listProducts({
+          baseUrl: effectiveEndpoint || "",
+        });
+        // Apply limit client-side
+        const limitedProducts = (response.items || []).slice(0, limit);
+        setProducts(limitedProducts);
+        setLoading(false);
+      } catch (err) {
+        console.error("Failed to load products:", err);
+        setLoading(false);
+      }
+    }
+
+    fetchProducts();
+  }, [effectiveEndpoint, limit]);
+
+  if (loading) {
+    return <div>Loading products...</div>;
+  }
+
+  return (
+    <div className={`grid ${gridClassName} ${className}`}>
+      {products.map((product) => (
+        <Product
+          key={product.id}
+          productId={product.id}
+          productData={product}
+        >
+          {children}
+        </Product>
+      ))}
+    </div>
+  );
+}