create-brainerce-store 1.71.0 → 1.72.0

package/templates/nextjs/base/src/ui/cart/reservation-countdown.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import { Clock } from 'lucide-react';
 import type { ReservationInfo } from 'brainerce';
 import { useTranslations } from '@/core/lib/translations';
@@ -8,12 +8,28 @@ import { cn } from '@/core/lib/utils';
 
 interface ReservationCountdownProps {
   reservation: ReservationInfo;
+  /**
+   * Fired once per reservation window when the timer reaches zero, including
+   * when the page opens on an already-expired reservation. The handler is
+   * expected to refresh the cart and gate checkout: this component only
+   * displays, it never decides what is still purchasable. Wire it to
+   * `useCartPage().onReservationExpired`.
+   */
+  onExpire?: () => void;
   className?: string;
 }
 
-export function ReservationCountdown({ reservation, className }: ReservationCountdownProps) {
+export function ReservationCountdown({
+  reservation,
+  onExpire,
+  className,
+}: ReservationCountdownProps) {
   const t = useTranslations('reservation');
-  const [remainingSeconds, setRemainingSeconds] = useState<number>(0);
+  // `null` means "not measured yet". Server-rendered HTML must not compute a
+  // time, or it disagrees with the client on hydration; starting at 0 instead
+  // would render the expired banner for one frame on a perfectly live
+  // reservation, and would fire onExpire on every mount.
+  const [remainingSeconds, setRemainingSeconds] = useState<number | null>(null);
 
   const calculateRemaining = useCallback(() => {
     if (!reservation.expiresAt) return 0;
@@ -22,8 +38,29 @@ export function ReservationCountdown({ reservation, className }: ReservationCoun
     return Math.max(0, Math.floor((expiresAtMs - nowMs) / 1000));
   }, [reservation.expiresAt]);
 
+  // Report each expiry window at most once. Keyed on `expiresAt` rather than a
+  // boolean, so the cart refresh that expiry triggers (which remounts this
+  // component) cannot bounce straight back into a second report.
+  const expiresAt = reservation.expiresAt;
+  const reportedExpiryRef = useRef<string | null>(null);
+  const onExpireRef = useRef(onExpire);
+  // Kept in a ref, and synced in an effect rather than during render, so a
+  // caller passing an inline arrow does not restart the timer every render.
   useEffect(() => {
-    setRemainingSeconds(calculateRemaining());
+    onExpireRef.current = onExpire;
+  }, [onExpire]);
+
+  const reportExpired = useCallback(() => {
+    if (!expiresAt) return;
+    if (reportedExpiryRef.current === expiresAt) return;
+    reportedExpiryRef.current = expiresAt;
+    onExpireRef.current?.();
+  }, [expiresAt]);
+
+  useEffect(() => {
+    const initial = calculateRemaining();
+    setRemainingSeconds(initial);
+    if (initial <= 0) reportExpired();
 
     const interval = setInterval(() => {
       const remaining = calculateRemaining();
@@ -31,18 +68,20 @@ export function ReservationCountdown({ reservation, className }: ReservationCoun
 
       if (remaining <= 0) {
         clearInterval(interval);
+        reportExpired();
       }
     }, 1000);
 
     return () => clearInterval(interval);
-  }, [calculateRemaining]);
+  }, [calculateRemaining, reportExpired]);
 
   if (!reservation.hasReservation) return null;
 
-  const minutes = Math.floor(remainingSeconds / 60);
-  const seconds = remainingSeconds % 60;
-  const isExpired = remainingSeconds <= 0;
-  const isUrgent = remainingSeconds > 0 && remainingSeconds < 120;
+  const displaySeconds = remainingSeconds ?? 0;
+  const minutes = Math.floor(displaySeconds / 60);
+  const seconds = displaySeconds % 60;
+  const isExpired = remainingSeconds !== null && remainingSeconds <= 0;
+  const isUrgent = displaySeconds > 0 && displaySeconds < 120;
 
   const displayMessage = reservation.countdownMessage
     ? reservation.countdownMessage.replace(
@@ -77,7 +116,10 @@ export function ReservationCountdown({ reservation, className }: ReservationCoun
 
       <div className="flex-1">
         {isExpired ? (
-          <p className="font-medium">{t('expired')}</p>
+          <>
+            <p className="font-medium">{t('expired')}</p>
+            <p className="text-xs opacity-90">{t('expiredHint')}</p>
+          </>
         ) : displayMessage ? (
           <p>{displayMessage}</p>
         ) : (

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

@@ -147,9 +147,27 @@ export function CartDrawer() {
               )}
               <p className="text-muted-foreground mt-1 text-xs">{t('shippingAtCheckout')}</p>
               <div className="mt-4 grid gap-2">
-                <Link href="/checkout" onClick={close} className="btn-primary btn-lg w-full">
-                  {t('proceedToCheckout')}
-                </Link>
+                {/* Same gate as the cart page: a line the server marked
+                    unavailable blocks checkout. A disabled-looking anchor
+                    would still navigate, so use a real disabled button. */}
+                {items.some((item) => item.isAvailable === false) ? (
+                  <>
+                    <button
+                      type="button"
+                      disabled
+                      className="btn-primary btn-lg w-full opacity-50"
+                    >
+                      {t('proceedToCheckout')}
+                    </button>
+                    <p className="text-destructive text-center text-xs">
+                      {t('unavailableItemsHint')}
+                    </p>
+                  </>
+                ) : (
+                  <Link href="/checkout" onClick={close} className="btn-primary btn-lg w-full">
+                    {t('proceedToCheckout')}
+                  </Link>
+                )}
                 <Link href="/cart" onClick={close} className="btn-outline btn-lg w-full">
                   {t('viewCart')}
                 </Link>

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

@@ -34,6 +34,17 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
   const unitPrice = parseFloat(item.unitPrice);
   const lineTotal = unitPrice * item.quantity;
 
+  // The server decides purchasability, per line. `isAvailable === false` means
+  // this line blocks checkout until it is removed, whether the stock ran out
+  // (a released reservation is the common cause) or the product/variant was
+  // withdrawn from sale. `unavailableReason` separates the two for the label.
+  const isUnavailable = item.isAvailable === false;
+  const unavailableLabel = isUnavailable
+    ? item.unavailableReason === 'OUT_OF_STOCK'
+      ? td('outOfStock')
+      : td('unavailable')
+    : null;
+
   async function handleQuantityChange(newQuantity: number) {
     if (newQuantity < 1 || updating) return;
 
@@ -81,6 +92,13 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
           {productName}
         </h3>
 
+        {/* Availability badge. This line blocks checkout while it shows. */}
+        {unavailableLabel && (
+          <span className="mt-1 inline-flex items-center rounded-full bg-destructive/10 px-2 py-0.5 text-xs font-medium text-destructive">
+            {unavailableLabel}
+          </span>
+        )}
+
         {/* Variant name */}
         {variantName && <p className="mt-0.5 text-xs text-muted-foreground">{variantName}</p>}
 
@@ -111,7 +129,7 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
             <button
               type="button"
               onClick={() => handleQuantityChange(item.quantity + 1)}
-              disabled={updating}
+              disabled={updating || isUnavailable}
               aria-label={td('increaseQuantity')}
               className="flex h-full w-9 items-center justify-center rounded-e-full transition-colors hover:bg-secondary disabled:opacity-40"
             >

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

@@ -18,7 +18,20 @@ import { IconBag, IconArrowEnd, IconShield } from '@/ui/shared/icons';
 export function CartView() {
   const t = useTranslations('cart');
   const tc = useTranslations('common');
-  const { cart, cartLoading, refreshCart, itemCount, cartRecs, upgrades, bundles } = useCartPage();
+  const tr = useTranslations('reservation');
+  const {
+    cart,
+    cartLoading,
+    refreshCart,
+    itemCount,
+    cartRecs,
+    upgrades,
+    bundles,
+    reservationExpired,
+    unavailableItems,
+    canProceedToCheckout,
+    onReservationExpired,
+  } = useCartPage();
 
   if (cartLoading) {
     return <LoadingSpinner size="lg" className="min-h-[60vh]" />;
@@ -52,9 +65,14 @@ export function CartView() {
         </span>
       </h1>
 
-      {/* Reservation countdown */}
+      {/* Reservation countdown. onExpire refreshes the cart and closes the
+          checkout gate below. Passing it is what makes expiry mean anything. */}
       {cart.reservation?.hasReservation && (
-        <ReservationCountdown reservation={cart.reservation} className="mt-4" />
+        <ReservationCountdown
+          reservation={cart.reservation}
+          onExpire={onReservationExpired}
+          className="mt-4"
+        />
       )}
 
       <div className="mt-6 grid grid-cols-1 items-start gap-8 lg:grid-cols-3 lg:gap-10">
@@ -112,10 +130,29 @@ export function CartView() {
             <FreeShippingBar />
             <CartSummary />
 
-            <Link href="/checkout" className="btn-primary btn-lg w-full">
-              {t('proceedToCheckout')}
-              <IconArrowEnd size={20} className="rtl-flip" />
-            </Link>
+            {/* Proceed to checkout. When the gate is closed this must be a
+                real disabled control, never a styled-down link: an anchor
+                ignores `disabled` and would still navigate. */}
+            {canProceedToCheckout ? (
+              <Link href="/checkout" className="btn-primary btn-lg w-full">
+                {t('proceedToCheckout')}
+                <IconArrowEnd size={20} className="rtl-flip" />
+              </Link>
+            ) : (
+              <div>
+                <button type="button" disabled className="btn-primary btn-lg w-full opacity-50">
+                  {t('proceedToCheckout')}
+                  <IconArrowEnd size={20} className="rtl-flip" />
+                </button>
+                <p className="mt-2 text-center text-xs text-destructive">
+                  {unavailableItems.length > 0
+                    ? t('unavailableItemsHint')
+                    : reservationExpired
+                      ? tr('expiredHint')
+                      : null}
+                </p>
+              </div>
+            )}
 
             <p className="flex items-center justify-center gap-1.5 text-xs text-muted-foreground">
               <IconShield size={16} />

package/templates/nextjs/designs/atelier/ui/cart/reservation-countdown.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import type { ReservationInfo } from 'brainerce';
 import { useTranslations } from '@/core/lib/translations';
 import { cn } from '@/core/lib/utils';
@@ -8,6 +8,14 @@ import { IconClock } from '@/ui/shared/icons';
 
 interface ReservationCountdownProps {
   reservation: ReservationInfo;
+  /**
+   * Fired once per reservation window when the timer reaches zero, including
+   * when the page opens on an already-expired reservation. Wired to
+   * `useCartPage().onReservationExpired`, which refreshes the cart and blocks
+   * checkout. This component only displays; it never decides what is still
+   * purchasable.
+   */
+  onExpire?: () => void;
   className?: string;
 }
 
@@ -16,9 +24,17 @@ interface ReservationCountdownProps {
  * prop comes from useCartPage().cart.reservation. Keeps the ticking logic
  * and the expired/urgent states (exposed via data-state).
  */
-export function ReservationCountdown({ reservation, className }: ReservationCountdownProps) {
+export function ReservationCountdown({
+  reservation,
+  onExpire,
+  className,
+}: ReservationCountdownProps) {
   const t = useTranslations('reservation');
-  const [remainingSeconds, setRemainingSeconds] = useState<number>(0);
+  // `null` means "not measured yet". Server-rendered HTML must not compute a
+  // time, or it disagrees with the client on hydration; starting at 0 instead
+  // would render the expired state for one frame on a perfectly live
+  // reservation, and would fire onExpire on every mount.
+  const [remainingSeconds, setRemainingSeconds] = useState<number | null>(null);
 
   const calculateRemaining = useCallback(() => {
     if (!reservation.expiresAt) return 0;
@@ -27,8 +43,29 @@ export function ReservationCountdown({ reservation, className }: ReservationCoun
     return Math.max(0, Math.floor((expiresAtMs - nowMs) / 1000));
   }, [reservation.expiresAt]);
 
+  // Report each expiry window at most once. Keyed on `expiresAt` rather than a
+  // boolean, so the cart refresh that expiry triggers (which remounts this
+  // component) cannot bounce straight back into a second report.
+  const expiresAt = reservation.expiresAt;
+  const reportedExpiryRef = useRef<string | null>(null);
+  const onExpireRef = useRef(onExpire);
+  // Kept in a ref, and synced in an effect rather than during render, so a
+  // caller passing an inline arrow does not restart the timer every render.
   useEffect(() => {
-    setRemainingSeconds(calculateRemaining());
+    onExpireRef.current = onExpire;
+  }, [onExpire]);
+
+  const reportExpired = useCallback(() => {
+    if (!expiresAt) return;
+    if (reportedExpiryRef.current === expiresAt) return;
+    reportedExpiryRef.current = expiresAt;
+    onExpireRef.current?.();
+  }, [expiresAt]);
+
+  useEffect(() => {
+    const initial = calculateRemaining();
+    setRemainingSeconds(initial);
+    if (initial <= 0) reportExpired();
 
     const interval = setInterval(() => {
       const remaining = calculateRemaining();
@@ -36,18 +73,20 @@ export function ReservationCountdown({ reservation, className }: ReservationCoun
 
       if (remaining <= 0) {
         clearInterval(interval);
+        reportExpired();
       }
     }, 1000);
 
     return () => clearInterval(interval);
-  }, [calculateRemaining]);
+  }, [calculateRemaining, reportExpired]);
 
   if (!reservation.hasReservation) return null;
 
-  const minutes = Math.floor(remainingSeconds / 60);
-  const seconds = remainingSeconds % 60;
-  const isExpired = remainingSeconds <= 0;
-  const isUrgent = remainingSeconds > 0 && remainingSeconds < 120;
+  const displaySeconds = remainingSeconds ?? 0;
+  const minutes = Math.floor(displaySeconds / 60);
+  const seconds = displaySeconds % 60;
+  const isExpired = remainingSeconds !== null && remainingSeconds <= 0;
+  const isUrgent = displaySeconds > 0 && displaySeconds < 120;
 
   const displayMessage = reservation.countdownMessage
     ? reservation.countdownMessage.replace(
@@ -72,7 +111,10 @@ export function ReservationCountdown({ reservation, className }: ReservationCoun
         <IconClock size={18} />
       </span>
       {isExpired ? (
-        <p>{t('expired')}</p>
+        <div>
+          <p>{t('expired')}</p>
+          <p className="text-xs font-normal opacity-90">{t('expiredHint')}</p>
+        </div>
       ) : displayMessage ? (
         <p>{displayMessage}</p>
       ) : (

package/templates/nextjs/ui-canvas/cart/cart-item.tsx

@@ -35,6 +35,17 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
   const unitPrice = parseFloat(item.unitPrice);
   const lineTotal = unitPrice * item.quantity;
 
+  // The server decides purchasability, per line. `isAvailable === false` means
+  // this line blocks checkout until it is removed, whether the stock ran out
+  // (a released reservation is the common cause) or the product/variant was
+  // withdrawn from sale. Keep the badge when you redesign this line.
+  const isUnavailable = item.isAvailable === false;
+  const unavailableLabel = isUnavailable
+    ? item.unavailableReason === 'OUT_OF_STOCK'
+      ? td('outOfStock')
+      : td('unavailable')
+    : null;
+
   async function handleQuantityChange(newQuantity: number) {
     if (newQuantity < 1 || updating) return;
 
@@ -80,6 +91,9 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
       <div>
         <h3>{productName}</h3>
 
+        {/* Availability badge. This line blocks checkout while it shows. */}
+        {unavailableLabel && <span data-state="unavailable">{unavailableLabel}</span>}
+
         {/* Variant name */}
         {variantName && <p>{variantName}</p>}
 
@@ -103,7 +117,7 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
             <button
               type="button"
               onClick={() => handleQuantityChange(item.quantity + 1)}
-              disabled={updating}
+              disabled={updating || isUnavailable}
               aria-label={td('increaseQuantity')}
             >
               +

package/templates/nextjs/ui-canvas/cart/cart-view.tsx

@@ -17,7 +17,20 @@ import { useTranslations } from '@/core/lib/translations';
 export function CartView() {
   const t = useTranslations('cart');
   const tc = useTranslations('common');
-  const { cart, cartLoading, refreshCart, itemCount, cartRecs, upgrades, bundles } = useCartPage();
+  const tr = useTranslations('reservation');
+  const {
+    cart,
+    cartLoading,
+    refreshCart,
+    itemCount,
+    cartRecs,
+    upgrades,
+    bundles,
+    reservationExpired,
+    unavailableItems,
+    canProceedToCheckout,
+    onReservationExpired,
+  } = useCartPage();
 
   if (cartLoading) {
     return <LoadingSpinner size="lg" />;
@@ -42,8 +55,11 @@ export function CartView() {
         {t('title')} ({itemCount} {itemCount === 1 ? tc('item') : tc('items')})
       </h1>
 
-      {/* Reservation countdown */}
-      {cart.reservation?.hasReservation && <ReservationCountdown reservation={cart.reservation} />}
+      {/* Reservation countdown. onExpire refreshes the cart and closes the
+          checkout gate below. Passing it is what makes expiry mean anything. */}
+      {cart.reservation?.hasReservation && (
+        <ReservationCountdown reservation={cart.reservation} onExpire={onReservationExpired} />
+      )}
 
       <div className="grid grid-cols-1 gap-8 lg:grid-cols-3">
         {/* Cart Items */}
@@ -91,7 +107,25 @@ export function CartView() {
           <FreeShippingBar />
           <CartSummary />
 
-          <Link href="/checkout">{t('proceedToCheckout')}</Link>
+          {/* Proceed to checkout. When the gate is closed this must be a real
+              disabled control, never a styled-down link: an anchor ignores
+              `disabled` and would still navigate. */}
+          {canProceedToCheckout ? (
+            <Link href="/checkout">{t('proceedToCheckout')}</Link>
+          ) : (
+            <>
+              <button type="button" disabled>
+                {t('proceedToCheckout')}
+              </button>
+              <p data-state="blocked">
+                {unavailableItems.length > 0
+                  ? t('unavailableItemsHint')
+                  : reservationExpired
+                    ? tr('expiredHint')
+                    : null}
+              </p>
+            </>
+          )}
 
           <Link href="/products">{tc('continueShopping')}</Link>
         </aside>

package/templates/nextjs/ui-canvas/cart/reservation-countdown.tsx

@@ -1,25 +1,42 @@
 'use client';
 
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import type { ReservationInfo } from 'brainerce';
 import { useTranslations } from '@/core/lib/translations';
 import { cn } from '@/core/lib/utils';
 
 interface ReservationCountdownProps {
   reservation: ReservationInfo;
+  /**
+   * Fired once per reservation window when the timer reaches zero, including
+   * when the page opens on an already-expired reservation. Wired to
+   * `useCartPage().onReservationExpired`, which refreshes the cart and blocks
+   * checkout. Keep the prop when you redesign this: the gate lives in the
+   * hook, but nothing tells it about the expiry unless this still calls it.
+   */
+  onExpire?: () => void;
   className?: string;
 }
 
 /**
  * DESIGN ME — stock-reservation countdown on the cart/checkout pages; the
  * `reservation` prop comes from useCartPage().cart.reservation. Keep the
- * ticking logic and the expired/urgent states (exposed via data-state).
+ * ticking logic, the `onExpire` call and the expired/urgent states (exposed
+ * via data-state).
  *
  * Building blocks: shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons are installed and ready to compose with.
  */
-export function ReservationCountdown({ reservation, className }: ReservationCountdownProps) {
+export function ReservationCountdown({
+  reservation,
+  onExpire,
+  className,
+}: ReservationCountdownProps) {
   const t = useTranslations('reservation');
-  const [remainingSeconds, setRemainingSeconds] = useState<number>(0);
+  // `null` means "not measured yet". Server-rendered HTML must not compute a
+  // time, or it disagrees with the client on hydration; starting at 0 instead
+  // would render the expired state for one frame on a perfectly live
+  // reservation, and would fire onExpire on every mount.
+  const [remainingSeconds, setRemainingSeconds] = useState<number | null>(null);
 
   const calculateRemaining = useCallback(() => {
     if (!reservation.expiresAt) return 0;
@@ -28,8 +45,29 @@ export function ReservationCountdown({ reservation, className }: ReservationCoun
     return Math.max(0, Math.floor((expiresAtMs - nowMs) / 1000));
   }, [reservation.expiresAt]);
 
+  // Report each expiry window at most once. Keyed on `expiresAt` rather than a
+  // boolean, so the cart refresh that expiry triggers (which remounts this
+  // component) cannot bounce straight back into a second report.
+  const expiresAt = reservation.expiresAt;
+  const reportedExpiryRef = useRef<string | null>(null);
+  const onExpireRef = useRef(onExpire);
+  // Kept in a ref, and synced in an effect rather than during render, so a
+  // caller passing an inline arrow does not restart the timer every render.
   useEffect(() => {
-    setRemainingSeconds(calculateRemaining());
+    onExpireRef.current = onExpire;
+  }, [onExpire]);
+
+  const reportExpired = useCallback(() => {
+    if (!expiresAt) return;
+    if (reportedExpiryRef.current === expiresAt) return;
+    reportedExpiryRef.current = expiresAt;
+    onExpireRef.current?.();
+  }, [expiresAt]);
+
+  useEffect(() => {
+    const initial = calculateRemaining();
+    setRemainingSeconds(initial);
+    if (initial <= 0) reportExpired();
 
     const interval = setInterval(() => {
       const remaining = calculateRemaining();
@@ -37,18 +75,20 @@ export function ReservationCountdown({ reservation, className }: ReservationCoun
 
       if (remaining <= 0) {
         clearInterval(interval);
+        reportExpired();
       }
     }, 1000);
 
     return () => clearInterval(interval);
-  }, [calculateRemaining]);
+  }, [calculateRemaining, reportExpired]);
 
   if (!reservation.hasReservation) return null;
 
-  const minutes = Math.floor(remainingSeconds / 60);
-  const seconds = remainingSeconds % 60;
-  const isExpired = remainingSeconds <= 0;
-  const isUrgent = remainingSeconds > 0 && remainingSeconds < 120;
+  const displaySeconds = remainingSeconds ?? 0;
+  const minutes = Math.floor(displaySeconds / 60);
+  const seconds = displaySeconds % 60;
+  const isExpired = remainingSeconds !== null && remainingSeconds <= 0;
+  const isUrgent = displaySeconds > 0 && displaySeconds < 120;
 
   const displayMessage = reservation.countdownMessage
     ? reservation.countdownMessage.replace(
@@ -64,7 +104,10 @@ export function ReservationCountdown({ reservation, className }: ReservationCoun
       className={cn(className)}
     >
       {isExpired ? (
-        <p>{t('expired')}</p>
+        <>
+          <p>{t('expired')}</p>
+          <p>{t('expiredHint')}</p>
+        </>
       ) : displayMessage ? (
         <p>{displayMessage}</p>
       ) : (