create-brainerce-store 1.79.0 → 1.81.0

package/templates/nextjs/base/src/ui/cart/cart-upgrade-banner.tsx

@@ -8,6 +8,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 { Button } from '@/components/ui/button';
 import { cn } from '@/core/lib/utils';
 
@@ -25,9 +26,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}`;
 
@@ -44,6 +56,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'
@@ -61,15 +83,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);
@@ -109,6 +188,21 @@ export function CartUpgradeBanner({
         <p className="text-foreground text-sm font-medium">
           {t('upgradeFor', { name: target.name, amount: formattedDelta })}
         </p>
+
+        {/*
+          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" className="text-destructive mt-1 text-xs">
+            {upgradeError === 'ORIGINAL_NOT_REMOVED'
+              ? t('upgradeOriginalNotRemoved')
+              : upgradeError === 'CART_FULL'
+                ? tp('cartFull')
+                : tp('addToCartFailed')}
+          </p>
+        )}
       </div>
 
       {/* Upgrade button */}

package/templates/nextjs/base/src/ui/layout/newsletter-signup.tsx

@@ -21,17 +21,26 @@
  * commonest reason a signup never becomes a subscriber, and the resend cooldown
  * means no second copy arrives for 24 hours.
  *
- * **Discount codes.** Subscribing mints nothing. For a "10% off your first
- * order" offer, the merchant creates a coupon in the dashboard with the
- * `customer_first_order` condition and you render that fixed code in the
- * success state — see the commented line below. Show it immediately: it must
- * not wait for the confirmation click, or the shopper loses the reason they
- * filled the form in.
+ * **The welcome offer.** `marketing.getBenefit()` returns what the merchant is
+ * offering people who confirm, or `null` when they offer nothing. Show its
+ * terms beside the field so the shopper knows what they are signing up for.
+ *
+ * ⛔ DO NOT RENDER A COUPON CODE HERE, now or after the success state. No coupon
+ * exists at either moment. It is minted when the recipient clicks the link in
+ * their own mailbox and is emailed to them there — which is exactly what stops a
+ * forwarded link handing the discount to someone who never asked. The
+ * confirmation page is served by the API and already shows the code, its expiry
+ * and its terms, so there is nothing here to poll for either.
+ *
+ * ⛔ There is no eligibility check to call, deliberately: a per-address answer
+ * would let anyone test who already subscribed. The offer is one per address per
+ * store, forever. Say so in the terms rather than trying to detect it.
  *
  * Rate limited to 3 requests / 60s per IP.
  */
 
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
+import type { PublicNewsletterBenefitOffer } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
 import { useTranslations } from '@/core/lib/translations';
 
@@ -42,6 +51,10 @@ export function NewsletterSignup() {
   const [loading, setLoading] = useState(false);
   const [done, setDone] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  // null covers both "no offer configured" and "the read failed". Neither is
+  // worth an error state on a footer signup: the form still works, it just
+  // promises nothing, and promising nothing is always safe.
+  const [offer, setOffer] = useState<PublicNewsletterBenefitOffer | null>(null);
 
   // Same source the contact form uses — <html lang> is set from the active
   // locale, and passing it is what decides the language of the confirmation
@@ -51,6 +64,31 @@ export function NewsletterSignup() {
     return undefined;
   }, []);
 
+  // Read once per mount. The offer belongs to the store, not to the visitor,
+  // so re-reading it per keystroke or per submit is wasted work.
+  useEffect(() => {
+    let cancelled = false;
+    getClient()
+      .marketing.getBenefit(locale)
+      .then((result) => {
+        if (!cancelled) setOffer(result);
+      })
+      .catch(() => {
+        // Silent on purpose. A failed offer read must not stop someone
+        // subscribing, and there is nothing the shopper could do about it.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [locale]);
+
+  const offerHeadline = offer
+    ? offer.headline?.trim() ||
+      (offer.discountType === 'PERCENTAGE'
+        ? t('offerPercent', { value: String(offer.discountValue) })
+        : t('offerAmount', { value: String(offer.discountValue) }))
+    : null;
+
   async function handleSubmit(e: React.FormEvent) {
     e.preventDefault();
     if (loading || !email.trim()) return;
@@ -80,11 +118,10 @@ export function NewsletterSignup() {
       <div className="space-y-1">
         <p className="text-sm font-medium">{t('checkEmailTitle')}</p>
         <p className="text-sm opacity-70">{t('checkEmailBody')}</p>
-        {/*
-          Merchant offering a signup discount? Render the coupon code here, now
-          — not after the confirmation click, which may never come:
-          <p className="text-sm font-medium">{t('discountCode', { code: 'WELCOME10' })}</p>
-        */}
+        {/* Says where the code comes from, without ever showing one. The coupon
+            is created by the confirmation click and arrives in the same inbox,
+            so "check your email" is the whole instruction. */}
+        {offer ? <p className="text-sm opacity-70">{t('offerByEmail')}</p> : null}
       </div>
     );
   }
@@ -96,6 +133,16 @@ export function NewsletterSignup() {
       </label>
       <p className="text-sm opacity-70">{t('subtitle')}</p>
 
+      {/* The merchant's own words when they wrote any, a plain statement of the
+          discount when they did not. Both are the promise the shopper is
+          agreeing to, so they belong above the input, not under the button. */}
+      {offerHeadline ? (
+        <div className="space-y-0.5">
+          <p className="text-sm font-medium">{offerHeadline}</p>
+          {offer?.terms ? <p className="text-xs opacity-70">{offer.terms}</p> : null}
+        </div>
+      ) : null}
+
       <div className="flex flex-wrap gap-2">
         <input
           id="newsletter-email"

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

@@ -8,6 +8,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 { Button } from '@/components/ui/button';
 import { Card } from '@/components/ui/card';
 import { Checkbox } from '@/components/ui/checkbox';
@@ -109,6 +110,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;
@@ -139,6 +141,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');
@@ -149,6 +152,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);
@@ -200,6 +207,16 @@ 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" className="text-destructive mt-3 text-sm">
+          {addError === 'CART_FULL' ? t('cartFull') : t('addToCartFailed')}
+        </p>
+      )}
     </Card>
   );
 }

package/templates/nextjs/base/src/ui/product/product-card.tsx

@@ -18,6 +18,7 @@ import { Card } from '@/components/ui/card';
 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 {
@@ -63,6 +64,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
@@ -84,6 +86,7 @@ export function ProductCard({ product, className }: ProductCardProps) {
     }
 
     if (adding || !canPurchase) return;
+    setAddError(null);
 
     try {
       setAdding(true);
@@ -99,6 +102,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);
@@ -224,6 +231,16 @@ export function ProductCard({ product, className }: ProductCardProps) {
           // `resolveStockInfo()` using ONE definition of 'this is a kit'.
           kitAvailable={product.type === 'KIT' ? product.kitAvailable : undefined}
         />
+
+        {/*
+          Quick-add refusal. The card has no other error surface, and without
+          this the shopper taps, the button resets, and nothing appears.
+        */}
+        {addError && (
+          <p className="text-destructive text-xs" role="alert">
+            {addError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}
+          </p>
+        )}
       </div>
     </Card>
   );

package/templates/nextjs/base/src/ui/product/product-client-section.tsx

@@ -141,6 +141,7 @@ export function ProductClientSection({
     setQuantity,
     addingToCart,
     addedMessage,
+    addToCartError,
     handleAddToCart,
     customizationFields,
     customizationValues,
@@ -437,6 +438,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 className="text-destructive text-sm" 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,

package/templates/nextjs/designs/atelier/ui/cart/cart-bundle-offer.tsx

@@ -6,6 +6,7 @@ import type { CartBundleOffer as CartBundleOfferType } from 'brainerce';
 import { formatPrice } from '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';
 import { IconBag } from '@/ui/shared/icons';
 
@@ -23,8 +24,10 @@ interface CartBundleOfferCardProps {
  */
 export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBundleOfferCardProps) {
   const t = useTranslations('cart');
+  const tp = useTranslations('productDetail');
   const currency = useCurrency();
   const [adding, setAdding] = useState(false);
+  const [addError, setAddError] = useState<AddToCartError | null>(null);
 
   const offered = offer.offeredProducts;
 
@@ -37,6 +40,7 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
 
   async function handleAdd() {
     if (adding) return;
+    setAddError(null);
     try {
       setAdding(true);
       const { getClient } = await import('@/core/lib/brainerce');
@@ -46,6 +50,10 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
       await client.addBundleToCart(cartId, offer.id);
       onAdd();
     } catch (err) {
+      // The cart page is where a shopper is most likely to be AT the 50-line
+      // cap, and a bundle adds one line per offered product. Logging alone
+      // left the button spinning back to idle with nothing added.
+      setAddError(toAddToCartError(err));
       console.error('Failed to add bundle:', err);
     } finally {
       setAdding(false);
@@ -105,6 +113,16 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
           {adding ? t('addingBundle') : t('addBundleItem')}
         </button>
       </div>
+
+      {/*
+        Why the bundle was refused. Without this the button resets and
+        nothing is added, which reads as a broken button.
+      */}
+      {addError && (
+        <p role="alert" className="text-destructive mt-2 text-xs">
+          {addError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}
+        </p>
+      )}
     </article>
   );
 }

package/templates/nextjs/designs/atelier/ui/cart/cart-item.tsx

@@ -9,6 +9,7 @@ import { useTranslations } from '@/core/lib/translations';
 import { useCurrency } from '@/core/lib/use-currency';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { cn } from '@/core/lib/utils';
+import { getErrorCode } from '@/core/lib/add-to-cart-error';
 import { OrderCustomizations } from '@/components/account/order-customizations';
 import { IconMinus, IconPlus, IconTrash } from '@/ui/shared/icons';
 
@@ -18,6 +19,17 @@ interface CartItemProps {
   className?: string;
 }
 
+/**
+ * Which `cart.*` string each refusal shows. A map rather than a ternary chain:
+ * four outcomes nest badly, and this keeps the copy next to the reason.
+ */
+const LINE_ERROR_KEYS = {
+  NOT_ENOUGH_STOCK: 'notEnoughStock',
+  ITEM_UNAVAILABLE: 'itemUnavailable',
+  UPDATE_FAILED: 'quantityUpdateFailed',
+  REMOVE_FAILED: 'removeFailed',
+} as const;
+
 /**
  * Single cart line: image, name, variant, unit price, quantity controls,
  * remove, line total; the `item` prop comes from useCartPage().cart.
@@ -25,9 +37,14 @@ interface CartItemProps {
 export function CartItem({ item, onUpdate, className }: CartItemProps) {
   const t = useTranslations('common');
   const td = useTranslations('productDetail');
+  const tc = useTranslations('cart');
   const currency = useCurrency();
   const [updating, setUpdating] = useState(false);
   const [removing, setRemoving] = useState(false);
+  // Why the last quantity change or removal did not take. Both calls used to
+  // fail into console.error alone: the row snapped back to the quantity it
+  // already had, or stayed put after Remove, and nothing on screen said why.
+  const [lineError, setLineError] = useState<keyof typeof LINE_ERROR_KEYS | null>(null);
 
   const productName = item.product.name;
   const imageUrl = getCartItemImage(item);
@@ -49,12 +66,28 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
   async function handleQuantityChange(newQuantity: number) {
     if (newQuantity < 1 || updating) return;
 
+    setLineError(null);
     try {
       setUpdating(true);
       const client = getClient();
       await client.smartUpdateCartItem(item.productId, newQuantity, item.variantId || undefined);
       onUpdate();
     } catch (err) {
+      // Two of these refusals are PERMANENT, and "please try again" would send
+      // the shopper round a loop that cannot succeed: INSUFFICIENT_STOCK (more
+      // than the inventory left) and PRODUCT_UNAVAILABLE (the line cannot be
+      // bought at all any more). Both get their own sentence; everything else
+      // is a blip worth one more tap. The 50-line cart cap is NOT a cause here
+      // at all, it only ever refuses a brand new line. Keep the log: the
+      // shopper gets the sentence, the developer still needs the detail.
+      const code = getErrorCode(err);
+      setLineError(
+        code === 'INSUFFICIENT_STOCK'
+          ? 'NOT_ENOUGH_STOCK'
+          : code === 'PRODUCT_UNAVAILABLE'
+            ? 'ITEM_UNAVAILABLE'
+            : 'UPDATE_FAILED'
+      );
       console.error('Failed to update quantity:', err);
     } finally {
       setUpdating(false);
@@ -64,12 +97,17 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
   async function handleRemove() {
     if (removing) return;
 
+    setLineError(null);
     try {
       setRemoving(true);
       const client = getClient();
       await client.smartRemoveFromCart(item.productId, item.variantId || undefined);
       onUpdate();
     } catch (err) {
+      // Nothing is lost when a remove fails, so the line is still there and
+      // still correct. Say so anyway: a Remove that visibly does nothing reads
+      // as a broken button.
+      setLineError('REMOVE_FAILED');
       console.error('Failed to remove item:', err);
     } finally {
       setRemoving(false);
@@ -157,6 +195,17 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
             {removing ? t('removing') : t('remove')}
           </button>
         </div>
+
+        {/*
+          Why the quantity change or the removal did not take. Keep it inside
+          this line's own column: it describes THIS row, and a shopper with ten
+          rows on screen has to be able to tell which one refused.
+        */}
+        {lineError && (
+          <p role="alert" className="text-destructive mt-2 text-xs font-medium">
+            {tc(LINE_ERROR_KEYS[lineError])}
+          </p>
+        )}
       </div>
 
       {/* Line total */}