create-brainerce-store 1.68.0 → 1.72.0

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>
       ) : (

package/templates/nextjs/ui-canvas/layout/newsletter-signup.tsx

@@ -0,0 +1,122 @@
+'use client';
+
+/**
+ * Newsletter signup (bare skeleton) — confirmed opt-in.
+ *
+ * ⛔ THIS DOES NOT SUBSCRIBE ANYONE. `marketing.subscribe()` creates the contact
+ * and mails them a confirmation link; the address is unmailable, and invisible
+ * to every campaign audience, until the recipient clicks it. Keep the success
+ * copy as "check your email" — never "you're subscribed", which is untrue until
+ * a click lands in a mailbox this code cannot see. Style this freely; do not
+ * change that sentence.
+ *
+ * ⛔ THE RESPONSE CARRIES NO INFORMATION. `{ ok: true }` comes back identically
+ * for a new address, one that already confirmed, one inside its 24-hour resend
+ * cooldown, and one suppressed after a hard bounce — otherwise this public form
+ * becomes a way to test who shops here. There is no branch to add.
+ *
+ * ⛔ KEEP THE HONEYPOT. It is the bot filter; deleting the input silently opens
+ * the form up.
+ */
+
+import { useMemo, useState } from 'react';
+import { getClient } from '@/core/lib/brainerce';
+import { useTranslations } from '@/core/lib/translations';
+
+export function NewsletterSignup() {
+  const t = useTranslations('newsletter');
+  const [email, setEmail] = useState('');
+  const [honeypot, setHoneypot] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [done, setDone] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // <html lang> carries the active locale, and passing it decides the language
+  // of the confirmation email. Omit it and a Hebrew shopper gets English.
+  const locale = useMemo(() => {
+    if (typeof document !== 'undefined') return document.documentElement.lang || undefined;
+    return undefined;
+  }, []);
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    if (loading || !email.trim()) return;
+
+    setLoading(true);
+    setError(null);
+    try {
+      await getClient().marketing.subscribe({
+        email: email.trim(),
+        locale,
+        source: 'footer',
+        honeypot,
+      });
+      setDone(true);
+      setEmail('');
+    } catch {
+      // A 429 lands here too — the copy stays generic rather than naming the
+      // rate limit, which would only tell an abuser where the edge is.
+      setError(t('genericError'));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (done) {
+    return (
+      <div>
+        {/* DESIGN ME — newsletter success state. Do NOT reword to "you're subscribed": the address is not on the list until the recipient clicks the emailed link. Naming the spam folder is deliberate — a filtered confirmation is the commonest reason a signup never converts, and no second copy is sent for 24 hours. */}
+        <p>{t('checkEmailTitle')}</p>
+        <p>{t('checkEmailBody')}</p>
+        {/*
+          Merchant offering a signup discount? Render the coupon code here, now
+          — not after the confirmation click, which may never come:
+          <p>{t('discountCode', { code: 'WELCOME10' })}</p>
+          The code comes from a dashboard coupon with the `customer_first_order`
+          condition; subscribing mints nothing on its own.
+        */}
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* DESIGN ME — newsletter signup: label, description, email input + submit button. Compose with the shadcn/ui primitives in src/components/ui (Button, Input, ...) + lucide-react icons. */}
+      <label htmlFor="newsletter-email">{t('title')}</label>
+      <p>{t('subtitle')}</p>
+
+      <input
+        id="newsletter-email"
+        type="email"
+        required
+        autoComplete="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder={t('placeholder')}
+      />
+      <button type="submit" disabled={loading}>
+        {loading ? t('submitting') : t('submit')}
+      </button>
+
+      {/*
+        Honeypot — keep it. Bots complete every text input; a human never sees
+        this one, so a non-empty value rejects the request server-side. Off-screen
+        rather than `display:none` (some bots skip hidden inputs), out of the tab
+        order and out of the accessibility tree. Style it however you like as long
+        as it stays invisible and focusable-by-nobody.
+      */}
+      <input
+        type="text"
+        name="company_website"
+        tabIndex={-1}
+        autoComplete="off"
+        aria-hidden="true"
+        value={honeypot}
+        onChange={(e) => setHoneypot(e.target.value)}
+        style={{ position: 'absolute', left: '-9999px', width: 1, height: 1 }}
+      />
+
+      {error ? <p role="alert">{error}</p> : null}
+    </form>
+  );
+}

package/templates/nextjs/ui-canvas/layout/site-footer.tsx.ejs

@@ -1,83 +1,87 @@
-/**
- * Storefront footer (bare skeleton) — fully driven by the merchant's
- * dashboard configuration.
- *
- * The merchant configures the footer in the Brainerce dashboard under
- *   Sell → Content → Footer
- *
- * Renders a brand block (store-name + social links), the merchant's link
- * columns, and a copyright bar.
- *
- * API contract:
- *   GET → client.content.footer.get('main', locale) → Content<'FOOTER'> | null
- *   Returns null on 404 — we render a minimal fallback so the layout never
- *   crashes when the merchant hasn't seeded the footer yet.
- */
-import * as React from 'react';
-import { Link } from '@/core/lib/navigation';
-import type { Content } from 'brainerce';
-
-interface SiteFooterProps {
-  /** Pre-fetched footer payload (server-side). `null` triggers fallback rendering. */
-  footer: Content<'FOOTER'> | null;
-  /** Store name shown in the brand block + fallback copyright. */
-  storeName?: string;
-}
-
-export function SiteFooter({ footer, storeName }: SiteFooterProps) {
-  const data = footer?.data;
-  const columns = data?.columns ?? [];
-  const social = data?.social ?? [];
-  const year = new Date().getFullYear();
-  const brandLabel = storeName ?? 'Store';
-
-  if (!data || (columns.length === 0 && !data.copyright && social.length === 0)) {
-    return (
-      <footer>
-        {/* DESIGN ME — footer (fallback branch): copyright only; Content<'FOOTER'> pre-fetched in the layout. Compose with the shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons. */}
-        <p>
-          © {year} {brandLabel}. All rights reserved.
-        </p>
-      </footer>
-    );
-  }
-
-  return (
-    <footer>
-      {/* DESIGN ME — footer: brand block, merchant link columns and social links (Content<'FOOTER'> pre-fetched in the layout), copyright bar. Compose with the shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons. */}
-      <div>
-        <Link href="/">{brandLabel}</Link>
-        {social.length > 0 ? (
-          <ul className="flex flex-wrap items-center gap-2">
-            {social.map((entry, idx) => (
-              <li key={`${entry.platform}-${idx}`}>
-                <a href={entry.url} target="_blank" rel="noopener noreferrer" aria-label={entry.platform}>
-                  {entry.platform}
-                </a>
-              </li>
-            ))}
-          </ul>
-        ) : null}
-      </div>
-
-      {columns.length > 0 ? (
-        <div className="flex flex-wrap gap-8">
-          {columns.map((col, idx) => (
-            <nav key={`${col.title}-${idx}`} aria-label={col.title}>
-              <h3>{col.title}</h3>
-              <ul>
-                {col.links.map((link, linkIdx) => (
-                  <li key={`${link.url}-${linkIdx}`}>
-                    <a href={link.url}>{link.label}</a>
-                  </li>
-                ))}
-              </ul>
-            </nav>
-          ))}
-        </div>
-      ) : null}
-
-      <p>{data.copyright ?? `© ${year} ${brandLabel}. All rights reserved.`}</p>
-    </footer>
-  );
-}
+/**
+ * Storefront footer (bare skeleton) — fully driven by the merchant's
+ * dashboard configuration.
+ *
+ * The merchant configures the footer in the Brainerce dashboard under
+ *   Sell → Content → Footer
+ *
+ * Renders a brand block (store-name + social links), the merchant's link
+ * columns, and a copyright bar.
+ *
+ * API contract:
+ *   GET → client.content.footer.get('main', locale) → Content<'FOOTER'> | null
+ *   Returns null on 404 — we render a minimal fallback so the layout never
+ *   crashes when the merchant hasn't seeded the footer yet.
+ */
+import * as React from 'react';
+import { Link } from '@/core/lib/navigation';
+import { NewsletterSignup } from './newsletter-signup';
+import type { Content } from 'brainerce';
+
+interface SiteFooterProps {
+  /** Pre-fetched footer payload (server-side). `null` triggers fallback rendering. */
+  footer: Content<'FOOTER'> | null;
+  /** Store name shown in the brand block + fallback copyright. */
+  storeName?: string;
+}
+
+export function SiteFooter({ footer, storeName }: SiteFooterProps) {
+  const data = footer?.data;
+  const columns = data?.columns ?? [];
+  const social = data?.social ?? [];
+  const year = new Date().getFullYear();
+  const brandLabel = storeName ?? 'Store';
+
+  if (!data || (columns.length === 0 && !data.copyright && social.length === 0)) {
+    return (
+      <footer>
+        {/* DESIGN ME — footer (fallback branch): copyright only; Content<'FOOTER'> pre-fetched in the layout. Compose with the shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons. */}
+        <p>
+          © {year} {brandLabel}. All rights reserved.
+        </p>
+        <NewsletterSignup />
+      </footer>
+    );
+  }
+
+  return (
+    <footer>
+      {/* DESIGN ME — footer: brand block, merchant link columns and social links (Content<'FOOTER'> pre-fetched in the layout), copyright bar. Compose with the shadcn/ui primitives in src/components/ui (Button, Card, Badge, Input, Select, Accordion, Dialog, Skeleton, ...) + lucide-react icons. */}
+      <div>
+        <Link href="/">{brandLabel}</Link>
+        {social.length > 0 ? (
+          <ul className="flex flex-wrap items-center gap-2">
+            {social.map((entry, idx) => (
+              <li key={`${entry.platform}-${idx}`}>
+                <a href={entry.url} target="_blank" rel="noopener noreferrer" aria-label={entry.platform}>
+                  {entry.platform}
+                </a>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+      </div>
+
+      {columns.length > 0 ? (
+        <div className="flex flex-wrap gap-8">
+          {columns.map((col, idx) => (
+            <nav key={`${col.title}-${idx}`} aria-label={col.title}>
+              <h3>{col.title}</h3>
+              <ul>
+                {col.links.map((link, linkIdx) => (
+                  <li key={`${link.url}-${linkIdx}`}>
+                    <a href={link.url}>{link.label}</a>
+                  </li>
+                ))}
+              </ul>
+            </nav>
+          ))}
+        </div>
+      ) : null}
+
+      <NewsletterSignup />
+
+      <p>{data.copyright ?? `© ${year} ${brandLabel}. All rights reserved.`}</p>
+    </footer>
+  );
+}

package/templates/nextjs/ui-canvas/product/back-in-stock-form.tsx

@@ -0,0 +1,151 @@
+'use client';
+
+/**
+ * Back-in-stock alert (bare skeleton) — "email me when this is back".
+ *
+ * ⛔ THIS IS NOT A NEWSLETTER SIGNUP. `stockAlerts.subscribe()` grants no
+ * marketing consent and creates no account; the person gets exactly one message,
+ * about this item, with a link that stops it. Label it "Notify me", never
+ * "Subscribe", and never hide it from someone who unsubscribed from marketing —
+ * there is no consent here to gate on. Style this freely; do not change that.
+ *
+ * ⛔ RENDER IT ONLY WHERE `canOfferStockAlert()` SAYS SO. Requests for anything
+ * else are silently discarded server-side, so a button in the wrong place looks
+ * like it worked and does nothing.
+ *
+ * ⛔ THE RESPONSE CARRIES NO INFORMATION. `{ ok: true }` comes back identically
+ * for a new request, a duplicate, an unknown product and an in-stock item —
+ * otherwise this public form becomes a way to read the store's stock levels.
+ * There is no branch to add.
+ *
+ * ⛔ DO NOT PROMISE TIMING. Stock has to hold for a few minutes, then alerts go
+ * out in waves sized to the units that returned, oldest request first. A shopper
+ * can sit through a restock without hearing. "We'll email you when it's back" is
+ * true; "you'll be the first to know" is not.
+ *
+ * ⛔ KEEP THE HONEYPOT. It is the bot filter; deleting the input silently opens
+ * the form up.
+ */
+
+import { useMemo, useState } from 'react';
+import type { InventoryInfo } from 'brainerce';
+import { getClient } from '@/core/lib/brainerce';
+import { useTranslations } from '@/core/lib/translations';
+
+/**
+ * The gate. Four ways the answer is no: the merchant switched the feature off
+ * for this storefront, the item is in stock, stock is not TRACKED (UNLIMITED
+ * never runs out, DISABLED is not for sale), or backorders are allowed — in
+ * which case the storefront can already sell it and an alert would tell someone
+ * to come back and do what they can already do.
+ */
+export function canOfferStockAlert(
+  inventory: InventoryInfo | null | undefined,
+  stockAlertsEnabled: boolean | undefined
+): boolean {
+  if (stockAlertsEnabled === false) return false;
+  if (!inventory) return false;
+  if (inventory.trackingMode !== 'TRACKED') return false;
+  if (inventory.canPurchase) return false;
+  // Older backends omit the field entirely; absent means no backorder.
+  return (inventory.backorderMode ?? 'NONE') === 'NONE';
+}
+
+interface BackInStockFormProps {
+  productId: string;
+  /**
+   * ⛔ Pass the SELECTED variant on any product with variants. Without it the
+   * alert waits on the product as a whole, so a shopper who wanted the medium is
+   * mailed when the small returns.
+   */
+  variantId?: string;
+}
+
+export function BackInStockForm({ productId, variantId }: BackInStockFormProps) {
+  const t = useTranslations('backInStock');
+  const [email, setEmail] = useState('');
+  const [honeypot, setHoneypot] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [done, setDone] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // <html lang> carries the active locale, and passing it decides the language
+  // of the alert email. Omit it and a Hebrew shopper gets English.
+  const locale = useMemo(() => {
+    if (typeof document !== 'undefined') return document.documentElement.lang || undefined;
+    return undefined;
+  }, []);
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    if (loading || !email.trim()) return;
+
+    setLoading(true);
+    setError(null);
+    try {
+      await getClient().stockAlerts.subscribe({
+        email: email.trim(),
+        productId,
+        variantId,
+        locale,
+        honeypot,
+      });
+      setDone(true);
+      setEmail('');
+    } catch {
+      // A 429 lands here too — keep the copy generic rather than naming the
+      // rate limit, which would only tell an abuser where the edge is.
+      setError(t('genericError'));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (done) {
+    return (
+      <div>
+        <p>{t('doneTitle')}</p>
+        <p>{t('doneBody')}</p>
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <label htmlFor="back-in-stock-email">{t('title')}</label>
+      <p>{t('subtitle')}</p>
+
+      <input
+        id="back-in-stock-email"
+        type="email"
+        required
+        autoComplete="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder={t('placeholder')}
+      />
+      <button type="submit" disabled={loading}>
+        {loading ? t('submitting') : t('submit')}
+      </button>
+
+      {/*
+        Honeypot. Bots complete every text input; a human never sees this one, so
+        a non-empty value rejects the request server-side. Off-screen rather than
+        `display:none` — some bots skip hidden inputs — and out of the tab order
+        and the accessibility tree.
+      */}
+      <input
+        type="text"
+        name="company_website"
+        tabIndex={-1}
+        autoComplete="off"
+        aria-hidden="true"
+        value={honeypot}
+        onChange={(e) => setHoneypot(e.target.value)}
+        style={{ position: 'absolute', left: '-9999px', width: 1, height: 1 }}
+      />
+
+      {error ? <p role="alert">{error}</p> : null}
+    </form>
+  );
+}