@snowcone-app/ui 0.8.3 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "React components for merchandise visualization and customization",
   "keywords": [
     "react",
@@ -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/__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");
+  });
+});