create-brainerce-store 1.80.0 → 1.81.0

package/templates/nextjs/ui-canvas/cart/cart-upgrade-banner.tsx

@@ -7,6 +7,7 @@ import { formatPrice } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
 import { useCurrency } from '@/core/lib/use-currency';
 import { useTranslations } from '@/core/lib/translations';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 
 interface CartUpgradeBannerProps {
@@ -30,9 +31,20 @@ export function CartUpgradeBanner({
   className,
 }: CartUpgradeBannerProps) {
   const t = useTranslations('cart');
+  const tp = useTranslations('productDetail');
   const currency = useCurrency();
   const [upgrading, setUpgrading] = useState(false);
   const [dismissed, setDismissed] = useState(false);
+  // True once the upgraded product is in the cart. A retry after a failed
+  // removal must retry the REMOVAL only, or a second press buys two of them.
+  const [upgradeAdded, setUpgradeAdded] = useState(false);
+  // `'ORIGINAL_NOT_REMOVED'` is kept local instead of being added to the shared
+  // `AddToCartError`: every other consumer of that type branches on
+  // `=== 'CART_FULL'` and would silently render "we could not add this" for a
+  // case where the add actually succeeded.
+  const [upgradeError, setUpgradeError] = useState<AddToCartError | 'ORIGINAL_NOT_REMOVED' | null>(
+    null
+  );
 
   const storageKey = `dismissed_upgrade_${suggestion.sourceProductId}`;
 
@@ -49,6 +61,16 @@ export function CartUpgradeBanner({
   if (dismissed) return null;
 
   const target = suggestion.targetProduct;
+
+  // A one-click upgrade cannot choose a variation for the shopper. When the
+  // target is VARIABLE with no pinned variant the backend says so
+  // (`requiresVariantSelection`), and adding it without a `variantId` is
+  // rejected outright, so offering the button here would only ever produce an
+  // error. Say nothing instead of promising something that cannot work; the
+  // shopper can still reach the product from the catalogue and pick a variation
+  // there. If you want to support this properly, add a variation picker to the
+  // banner and pass the chosen `variantId` to `smartAddToCart` below.
+  if (target.requiresVariantSelection && !target.pinnedVariant?.id) return null;
   const firstImage = target.images?.[0];
   const imageUrl = firstImage
     ? typeof firstImage === 'string'
@@ -66,15 +88,72 @@ export function CartUpgradeBanner({
     setDismissed(true);
   }
 
+  /**
+   * Swap the cart line for the upgraded product: ADD FIRST, THEN REMOVE.
+   *
+   * The order is load-bearing, not incidental. This used to remove and then
+   * add, so any failure of the add (a network blip, the target selling out, or
+   * the 50-line cart cap answering 400) left the shopper with NEITHER product
+   * and nothing on screen: the remove had committed, the add had not, and the
+   * whole thing went to the console. Adding first means a failed add leaves the
+   * cart exactly as it was.
+   *
+   * The other candidate, remove-then-add with a compensating re-add, was
+   * rejected because the compensation is not a restore. A cart line carries
+   * `modifiers`, `customizations`, `notes` and `parentCartItemId`, and
+   * `smartAddToCart` accepts none of those back in that shape (it takes
+   * `selections`), so re-adding would silently strip the shopper's choices even
+   * when it SUCCEEDS, and orphan a nested-combo child line. The SDK has no swap
+   * primitive to sidestep the choice with (`smartRemoveFromCart` is only
+   * `smartUpdateCartItem(productId, 0, variantId)`), so these two orderings are
+   * the whole option space.
+   *
+   * The accepted cost: the cart is briefly one line longer, so a cart sitting
+   * at the 50-line cap refuses a swap that is net-zero. The shopper is told the
+   * cart is full and the cart is untouched, which is a far better outcome than
+   * losing the line. Do NOT add a "fall back to remove-then-add when the cart is
+   * full" path; that hands the loss window back for a rare edge.
+   */
   async function handleUpgrade() {
     if (upgrading) return;
+    setUpgradeError(null);
     try {
       setUpgrading(true);
       const client = getClient();
-      await client.smartRemoveFromCart(cartItem.productId, cartItem.variantId || undefined);
-      await client.smartAddToCart({ productId: target.id, quantity: cartItem.quantity });
+      if (!upgradeAdded) {
+        // A VARIABLE target needs a variant. The backend already tells us which
+        // case we are in (`pinnedVariant` when the slot pins one,
+        // `requiresVariantSelection` when the shopper must choose), but this
+        // banner used to send neither -- and `CartService.addItem` rejects a
+        // VARIABLE product with no `variantId`, so an upgrade to a variable
+        // product failed EVERY time, not occasionally. Under the old
+        // remove-then-add ordering that silently destroyed the original line.
+        // The unpinned case is filtered out before render, so by here either a
+        // pin exists or the target is SIMPLE.
+        await client.smartAddToCart({
+          productId: target.id,
+          quantity: cartItem.quantity,
+          ...(target.pinnedVariant?.id ? { variantId: target.pinnedVariant.id } : {}),
+        });
+        setUpgradeAdded(true);
+      }
+      try {
+        await client.smartRemoveFromCart(cartItem.productId, cartItem.variantId || undefined);
+      } catch (err) {
+        // The upgrade IS in the cart and only the old line survived, so nothing
+        // was lost and this is not a failed upgrade. Deliberately does NOT call
+        // onUpgrade(): the backend drops an upgrade suggestion once its target
+        // is in the cart, so refreshing here unmounts this banner and takes the
+        // message with it. Pressing Upgrade again retries the removal alone.
+        setUpgradeError('ORIGINAL_NOT_REMOVED');
+        console.error('Upgraded, but could not remove the original cart item:', err);
+        return;
+      }
       onUpgrade();
     } catch (err) {
+      // The add failed, so the cart is untouched. Say so: logging alone left the
+      // button spinning back to idle with nothing changed and no explanation.
+      setUpgradeError(toAddToCartError(err));
       console.error('Failed to upgrade cart item:', err);
     } finally {
       setUpgrading(false);
@@ -100,6 +179,20 @@ export function CartUpgradeBanner({
       <button type="button" onClick={handleDismiss} aria-label={t('dismissUpgrade')}>
         ×
       </button>
+
+      {/*
+        Why the swap did not complete. Without this the button resets, the cart
+        looks unchanged, and the shopper has no idea whether anything happened.
+      */}
+      {upgradeError && (
+        <p role="alert">
+          {upgradeError === 'ORIGINAL_NOT_REMOVED'
+            ? t('upgradeOriginalNotRemoved')
+            : upgradeError === 'CART_FULL'
+              ? tp('cartFull')
+              : tp('addToCartFailed')}
+        </p>
+      )}
     </div>
   );
 }

package/templates/nextjs/ui-canvas/product/frequently-bought-together.tsx

@@ -7,6 +7,7 @@ import { formatPrice } from 'brainerce';
 import { useCart, useStoreInfo } from '@/core/providers/store-provider';
 import { useCurrency } from '@/core/lib/use-currency';
 import { useTranslations } from '@/core/lib/translations';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 
 interface FrequentlyBoughtTogetherProps {
@@ -90,6 +91,7 @@ export function FrequentlyBoughtTogether({
 
   const [selected, setSelected] = useState<Set<string>>(() => new Set(crossSells.map((i) => i.id)));
   const [adding, setAdding] = useState(false);
+  const [addError, setAddError] = useState<AddToCartError | null>(null);
 
   if (!storeInfo?.upsell?.frequentlyBoughtTogetherEnabled) return null;
   if (crossSells.length === 0) return null;
@@ -120,6 +122,7 @@ export function FrequentlyBoughtTogether({
 
   async function handleAddAll() {
     if (adding || selected.size === 0) return;
+    setAddError(null);
     try {
       setAdding(true);
       const { getClient } = await import('@/core/lib/brainerce');
@@ -130,6 +133,10 @@ export function FrequentlyBoughtTogether({
       }
       await refreshCart();
     } catch (err) {
+      // The loop is not transactional: if the cart hits its 50-line cap
+      // part-way through, the earlier items ARE in the cart and the rest are
+      // not. Saying so beats a silent stop the shopper reads as a dead button.
+      setAddError(toAddToCartError(err));
       console.error('Failed to add items to cart:', err);
     } finally {
       setAdding(false);
@@ -177,6 +184,14 @@ export function FrequentlyBoughtTogether({
           {adding ? t('addingAll') : t('addSelectedToCart')}
         </button>
       </div>
+
+      {/*
+        Why the add was refused. Some items may already be in the cart:
+        the loop above adds one at a time and stops at the first refusal.
+      */}
+      {addError && (
+        <p role="alert">{addError === 'CART_FULL' ? t('cartFull') : t('addToCartFailed')}</p>
+      )}
     </section>
   );
 }

package/templates/nextjs/ui-canvas/product/product-card.tsx

@@ -14,6 +14,7 @@ import { DiscountBadge } from '@/ui/product/discount-badge';
 import { useCart } from '@/core/providers/store-provider';
 import { useCurrency } from '@/core/lib/use-currency';
 import { trackAddToCart } from '@/core/lib/tracking';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 
 interface ProductCardProps {
@@ -58,6 +59,7 @@ export function ProductCard({ product, className }: ProductCardProps) {
 
   const [adding, setAdding] = useState(false);
   const [added, setAdded] = useState(false);
+  const [addError, setAddError] = useState<AddToCartError | null>(null);
 
   // ⛔ A KIT carries NO `inventory` object — its stock is on `kitAvailable`
   // (`null` = unlimited, `0` = not sellable). Reading `inventory` here left a
@@ -79,6 +81,7 @@ export function ProductCard({ product, className }: ProductCardProps) {
     }
 
     if (adding || !canPurchase) return;
+    setAddError(null);
 
     try {
       setAdding(true);
@@ -94,6 +97,10 @@ export function ProductCard({ product, className }: ProductCardProps) {
       setAdded(true);
       setTimeout(() => setAdded(false), 2000);
     } catch (err) {
+      // Quick-add used to fail in silence: the button spun, reset, and the
+      // item never appeared. A cart at the 50-line cap is the commonest
+      // cause and the shopper can fix it, so say so on the card.
+      setAddError(toAddToCartError(err));
       console.error('Failed to add to cart:', err);
     } finally {
       setAdding(false);
@@ -169,6 +176,14 @@ export function ProductCard({ product, className }: ProductCardProps) {
           {added ? tp('addedToCart') : isVariable ? tProd('selectOptions') : tp('addToCart')}
         </button>
       )}
+
+      {/*
+        Quick-add refusal. The card has no other error surface, and without
+        this the shopper taps, the button resets, and nothing appears.
+      */}
+      {addError && (
+        <p role="alert">{addError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}</p>
+      )}
     </article>
   );
 }

package/templates/nextjs/ui-canvas/product/product-client-section.tsx

@@ -107,6 +107,7 @@ export function ProductClientSection({
     setQuantity,
     addingToCart,
     addedMessage,
+    addToCartError,
     handleAddToCart,
     customizationFields,
     customizationValues,
@@ -347,6 +348,18 @@ export function ProductClientSection({
             </button>
           </div>
 
+          {/*
+            Why the add was refused. Deliberately OUTSIDE the modifier block
+            above: that block only renders when the product HAS modifier
+            groups, so a refusal shown there would be invisible on almost
+            every product and the shopper would just watch the button reset.
+          */}
+          {addToCartError && (
+            <p role="alert">
+              {addToCartError === 'CART_FULL' ? t('cartFull') : t('addToCartFailed')}
+            </p>
+          )}
+
           {/*
             Sold out is not the end of the page. `canOfferStockAlert` is the whole
             gate — it also covers the merchant's switch and backorderable items,