@snowcone-app/ui 0.8.3 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "description": "React components for merchandise visualization and customization",
   "keywords": [
     "react",
@@ -103,7 +103,7 @@
     "react-instantsearch": "^7.15.5",
     "react-zoom-pan-pinch": "^3.6.4",
     "tailwind-merge": "^3.0.0",
-    "@snowcone-app/sdk": "0.24.2"
+    "@snowcone-app/sdk": "0.24.3"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.2",
@@ -121,7 +121,7 @@
     "@vitejs/plugin-react": "^4.7.0",
     "@vueless/storybook-dark-mode": "^10.0.3",
     "jsdom": "^24.1.0",
-    "next": "15.5.24",
+    "next": "16.4.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "rimraf": "^6.1.2",

package/src/composed/AddToCart.tsx

@@ -14,14 +14,23 @@ export interface AddToCartProps {
   text?: string;
   loadingText?: string;
   successText?: string;
+  /** Button text after a failed add; the error's message is announced in a
+   *  `role="alert"` below the button and the button stays enabled to retry. */
+  errorText?: string;
   disabled?: boolean;
   className?: string;
   quantity?: number;
-  onClick?: (cartDetail: any) => void;
+  /** Performs the add. Return a Promise and the button waits for it: "Added!"
+   *  only after it resolves; a rejection shows the error state. */
+  onClick?: (cartDetail: any) => void | Promise<unknown>;
   onError?: (error: Error) => void;
+  /** Fake delay used only when there is no `onClick` (demos). */
   simulateDelay?: number;
 }
 
+/** `data-add-to-cart` on the button — assert on this, not the label text. */
+export type AddToCartStatus = "idle" | "adding" | "added" | "error";
+
 /**
  * AddToCart - Add to cart button with validation and loading states
  *
@@ -31,8 +40,11 @@ export interface AddToCartProps {
  *
  * Features:
  * - Automatic selection validation before allowing add
- * - Loading state with customizable text
- * - Success state with visual feedback (green background)
+ * - Loading state with customizable text; waits for an async `onClick`
+ * - Success only after `onClick` resolves; a rejection shows `errorText`
+ *   plus the error message in a `role="alert"`, and the button stays
+ *   enabled to retry (never a silent "Added!")
+ * - `data-add-to-cart="idle|adding|added|error"` for tests and agents
  * - Automatic cart detail generation with variant info
  * - Simulated delay for cart operations
  * - Screen reader announcements for state changes
@@ -57,9 +69,10 @@ export interface AddToCartProps {
  * <Product productId="shirt-123">
  *   <ProductOptions />
  *   <AddToCart
- *     onClick={(cartDetail) => {
- *       console.log('Added to cart:', cartDetail);
- *       // Add to your cart state/API
+ *     onClick={async (cartDetail) => {
+ *       // Throw (or reject) if the add fails — the button shows the error.
+ *       const res = await fetch('/api/cart', { method: 'POST', body: JSON.stringify(cartDetail) });
+ *       if (!res.ok) throw new Error('Could not add to cart');
  *     }}
  *   />
  * </Product>
@@ -89,27 +102,26 @@ export interface AddToCartProps {
  *
  * @example
  * ```tsx
- * // Faster simulation for testing
- * <AddToCart
- *   simulateDelay={500}
- *   onClick={(detail) => console.log(detail)}
- * />
+ * // Demo without a real cart: a simulated delay, then "Added!"
+ * <AddToCart simulateDelay={500} />
  * ```
  *
  * @param text - Button text in default state (default: "Add to Bag")
  * @param loadingText - Button text while adding (default: "Adding...")
  * @param successText - Button text after successful add (default: "Added!")
+ * @param errorText - Button text after a failed add (default: "Couldn't add — try again")
  * @param disabled - Force button to disabled state
  * @param className - Additional CSS classes for button
  * @param quantity - Number of items to add (default: 1)
- * @param onClick - Callback with cart detail after successful add
+ * @param onClick - Performs the add with the cart detail; may return a Promise, which the button awaits
  * @param onError - Callback when add fails with error
- * @param simulateDelay - Delay in ms to simulate cart operation (default: 1000)
+ * @param simulateDelay - Delay in ms to simulate a cart operation when there is no `onClick` (default: 1000)
  */
 export function AddToCart({
   text = "Add to Bag",
   loadingText = "Adding...",
   successText = "Added!",
+  errorText = "Couldn't add — try again",
   disabled = false,
   className = "",
   quantity = 1,
@@ -119,8 +131,10 @@ export function AddToCart({
 }: AddToCartProps) {
   const context = useProduct();
   const shopContext = useShopOptional();
-  const [loading, setLoading] = useState(false);
-  const [success, setSuccess] = useState(false);
+  const [status, setStatus] = useState<AddToCartStatus>("idle");
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const loading = status === "adding";
+  const success = status === "added";
 
   // Dev-mode warning for missing providers
   useEffect(() => {
@@ -151,7 +165,8 @@ export function AddToCart({
     if (isDisabled || !product) return;
 
     try {
-      setLoading(true);
+      setStatus("adding");
+      setErrorMessage(null);
 
       // Create cart detail using ui-core
       const cartDetail = createCartDetail({
@@ -166,28 +181,26 @@ export function AddToCart({
         throw new Error("Invalid selection - unable to create cart detail");
       }
 
-      // Simulate cart operation delay
-      await simulateCartOperation(simulateDelay);
-
-      // Call onClick handler with cart detail
-      onClick?.(cartDetail);
-
-      // Show success state
-      setSuccess(true);
+      if (onClick) {
+        // The host performs the add; success means it resolved.
+        await onClick(cartDetail);
+      } else {
+        await simulateCartOperation(simulateDelay);
+      }
 
-      // Reset success after 2 seconds
+      setStatus("added");
       setTimeout(() => {
-        setSuccess(false);
+        setStatus((s) => (s === "added" ? "idle" : s));
       }, 2000);
     } catch (error) {
-      onError?.(error as Error);
-      console.error("Add to cart failed:", error);
-    } finally {
-      setLoading(false);
+      const err = error instanceof Error ? error : new Error(String(error));
+      setStatus("error");
+      setErrorMessage(err.message);
+      onError?.(err);
     }
   };
 
-  const buttonText = loading ? loadingText : success ? successText : text;
+  const buttonText = loading ? loadingText : success ? successText : status === "error" ? errorText : text;
 
   // Default styles that work out of the box - LLM-friendly
   // These are always applied, then className can override/extend them
@@ -204,6 +217,7 @@ export function AddToCart({
   const getAriaLabel = () => {
     if (loading) return loadingText;
     if (success) return successText;
+    if (status === "error") return `${errorText} - ${product?.name || "product"}`;
     if (!product) return text;
     return `${text} - ${product.name || 'product'}`;
   };
@@ -221,9 +235,15 @@ export function AddToCart({
         onClick={handleClick}
         aria-label={getAriaLabel()}
         aria-busy={loading}
+        data-add-to-cart={status}
       >
         {buttonText}
       </button>
+      {status === "error" && errorMessage && (
+        <p role="alert" className="mt-2 text-sm text-destructive">
+          {errorMessage}
+        </p>
+      )}
     </>
   );
 }

package/src/composed/ColorPicker.tsx

@@ -43,7 +43,7 @@ const QUICK_COLORS = [
  * ```tsx
  * import { Product, ColorPicker } from '@snowcone-app/ui';
  *
- * <Product productId="AR2P3G">
+ * <Product productId="CAXHQC">
  *   <ColorPicker placement="Crown" defaultColor="#ff0000" />
  * </Product>
  * ```

package/src/composed/HeroProductImage.tsx

@@ -24,6 +24,7 @@ import {
   getMockupUrl,
   type Design,
   resolveVariantId,
+  resolvePreviewVariantId,
   resolveMockupId,
 } from "@snowcone-app/sdk";
 
@@ -232,13 +233,18 @@ export const HeroProductImage = memo(function HeroProductImage({
   const actualProductId = product?.id || productId || context?.product?.id;
 
   // Resolve variant and mockup IDs - MOVED UP for initial URL computation
-  const actualGvid = useMemo(() => {
+  const selectedGvid = useMemo(() => {
     return resolveVariantId(context, gvid, variantId);
   }, [gvid, variantId, context?.selection, context?.combinations]);
 
   const actualMockupId = useMemo(() => {
-    return resolveMockupId(context, actualGvid, mockupId);
-  }, [mockupId, actualGvid, context]);
+    return resolveMockupId(context, selectedGvid, mockupId);
+  }, [mockupId, selectedGvid, context]);
+
+  // What this image renders: a selected size with no scene previews a listed one. A variant the caller named is theirs.
+  const actualGvid = useMemo(() => {
+    return gvid || variantId ? selectedGvid : resolvePreviewVariantId(context, selectedGvid, actualMockupId);
+  }, [gvid, variantId, selectedGvid, actualMockupId, context]);
 
   // The server refused THIS mockup for the session (its scene failed render
   // parity — E_MOCKUP_NOT_BLESSED). Shown as unavailable on top of whatever

package/src/composed/ProductGallery.tsx

@@ -23,7 +23,7 @@ export interface ProductGalleryProps extends UseProductGalleryOptions {
  * 2. List all products: Pass empty array or omit productIds
  *
  * @example Specific products
- * <ProductGallery productIds={["BEEB77", "AR2P3G", "KMYKUK"]}>
+ * <ProductGallery productIds={["BEEB77", "CAXHQC", "KMYKUK"]}>
  *   {(products, loading, error) => (
  *     <div className="grid grid-cols-3 gap-4">
  *       {products.map(product => (

package/src/composed/__tests__/AddToCart.async.test.tsx

@@ -0,0 +1,104 @@
+/**
+ * AddToCart waits for the host's add and never reports a failure as success.
+ *
+ * - An async `onClick` is awaited: "Added!" only after it resolves.
+ * - A rejection shows `errorText`, puts the error message in a role=alert,
+ *   calls `onError`, and leaves the button enabled to retry.
+ * - `data-add-to-cart` exposes idle | adding | added | error.
+ * - With no `onClick`, the demo delay still ends in "Added!".
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
+
+vi.mock("../../patterns/Product", () => {
+  const ctx = {
+    product: { id: "P1", name: "Framed Canvas" },
+    selection: {},
+    combinations: [],
+    optionAttributes: {},
+  };
+  return { useProduct: () => ctx, useProductOptional: () => ctx };
+});
+vi.mock("../../patterns/ShopProvider", () => ({ useShopOptional: () => null }));
+vi.mock("../../utils/devWarnings", () => ({ checkProviders: () => {} }));
+vi.mock("@snowcone-app/sdk", () => ({
+  validateProductSelection: () => true,
+  createCartDetail: (d: { productId: string; quantity: number }) => ({ productId: d.productId, quantity: d.quantity }),
+  simulateCartOperation: () => Promise.resolve(),
+}));
+
+import { AddToCart } from "../AddToCart";
+
+afterEach(cleanup);
+
+function deferred() {
+  let resolve!: () => void;
+  let reject!: (e: Error) => void;
+  const promise = new Promise<void>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+const button = () => screen.getByRole("button");
+
+describe("AddToCart with an async onClick", () => {
+  it("stays 'adding' until the add resolves, then shows success", async () => {
+    const add = deferred();
+    render(<AddToCart onClick={() => add.promise} />);
+
+    fireEvent.click(button());
+    await act(async () => {});
+    expect(button().getAttribute("data-add-to-cart")).toBe("adding");
+    expect(button().textContent).toBe("Adding...");
+
+    await act(async () => add.resolve());
+    expect(button().getAttribute("data-add-to-cart")).toBe("added");
+    expect(button().textContent).toBe("Added!");
+  });
+
+  it("shows the error, alerts its message, calls onError, and allows a retry", async () => {
+    const onError = vi.fn();
+    const onClick = vi.fn(
+      (): Promise<void> => Promise.reject(new Error("Couldn't add Framed Canvas to your bag (error 500).")),
+    );
+    render(<AddToCart onClick={onClick} onError={onError} errorText="Try again" />);
+
+    await act(async () => fireEvent.click(button()));
+    expect(button().getAttribute("data-add-to-cart")).toBe("error");
+    expect(button().textContent).toBe("Try again");
+    expect(screen.getByRole("alert").textContent).toBe("Couldn't add Framed Canvas to your bag (error 500).");
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect((button() as HTMLButtonElement).disabled).toBe(false);
+
+    onClick.mockImplementationOnce(() => Promise.resolve());
+    await act(async () => fireEvent.click(button()));
+    expect(button().getAttribute("data-add-to-cart")).toBe("added");
+    expect(screen.queryByRole("alert")).toBeNull();
+    expect(onClick).toHaveBeenCalledTimes(2);
+  });
+
+  it("treats a synchronous throw like a rejection", async () => {
+    render(
+      <AddToCart
+        onClick={() => {
+          throw new Error("boom");
+        }}
+      />,
+    );
+    await act(async () => fireEvent.click(button()));
+    expect(button().getAttribute("data-add-to-cart")).toBe("error");
+    expect(screen.getByRole("alert").textContent).toBe("boom");
+  });
+});
+
+describe("AddToCart without onClick (demo)", () => {
+  it("ends in success after the simulated delay", async () => {
+    render(<AddToCart />);
+    expect(button().getAttribute("data-add-to-cart")).toBe("idle");
+    await act(async () => fireEvent.click(button()));
+    expect(button().getAttribute("data-add-to-cart")).toBe("added");
+  });
+});

package/src/hooks/useProductGallery.ts

@@ -49,7 +49,7 @@ export interface UseProductGalleryReturn {
  * ```tsx
  * // Fetch specific products
  * const { products, loading, error, refetch } = useProductGallery(
- *   ['BEEB77', 'AR2P3G'],
+ *   ['BEEB77', 'CAXHQC'],
  *   { endpoint: 'http://localhost:3000', mode: 'mock' }
  * );
  *

package/src/patterns/RealtimeProvider.tsx

@@ -37,7 +37,7 @@ import React, {
   useMemo,
 } from "react";
 import { useRealtimeMockup } from "@snowcone-app/sdk/react";
-import { resolveVariantId as resolveVariantIdUtil } from "@snowcone-app/sdk";
+import { resolvePreviewVariantId, resolveVariantId as resolveVariantIdUtil } from "@snowcone-app/sdk";
 import type {
   RealtimeRenderError,
   MockupResult as SdkMockupResult,
@@ -987,10 +987,9 @@ export function RealtimeProvider({
     const placements = product.placements || [];
 
     // Resolve variant ID based on current selection
-    const variantId = resolveVariantIdUtil(
+    const variantId = resolvePreviewVariantId(
       productContext,
-      undefined,
-      undefined
+      resolveVariantIdUtil(productContext, undefined, undefined)
     );
 
     // Check if we need to send config:

package/src/patterns/__tests__/RealtimeProvider.cropDelivery.test.tsx

@@ -64,6 +64,7 @@ vi.mock("@snowcone-app/sdk/react", () => ({
 
 vi.mock("@snowcone-app/sdk", () => ({
   resolveVariantId: () => "gv1",
+  resolvePreviewVariantId: (_context: unknown, variantId: string) => variantId,
 }));
 
 vi.mock("../Product", () => {