create-brainerce-store 1.68.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/base/src/ui/layout/newsletter-signup.tsx

@@ -0,0 +1,143 @@
+'use client';
+
+/**
+ * Newsletter signup — 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. That is why the
+ * success state below says "check your email" and never "you're subscribed" —
+ * the second is untrue until a click lands in a mailbox this code cannot see,
+ * and most people never click.
+ *
+ * ⛔ THE RESPONSE CARRIES NO INFORMATION. `{ ok: true }` comes back identically
+ * for a brand-new address, one that confirmed months ago, one still inside its
+ * 24-hour resend cooldown, and one suppressed after a hard bounce. That is
+ * deliberate: a response that distinguished them would turn this public form
+ * into a way to test whether a given person shops here. There is nothing to
+ * branch on — render one success state and stop.
+ *
+ * Naming the spam folder is not padding. A filtered confirmation is the single
+ * 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.
+ *
+ * Rate limited to 3 requests / 60s per IP.
+ */
+
+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);
+
+  // 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
+  // email. Omit it on a Hebrew storefront and the 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 explaining
+      // the rate limit, which would only tell an abuser where the edge is.
+      setError(t('genericError'));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (done) {
+    return (
+      <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>
+        */}
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-2">
+      <label htmlFor="newsletter-email" className="block text-sm font-medium">
+        {t('title')}
+      </label>
+      <p className="text-sm opacity-70">{t('subtitle')}</p>
+
+      <div className="flex flex-wrap gap-2">
+        <input
+          id="newsletter-email"
+          type="email"
+          required
+          autoComplete="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder={t('placeholder')}
+          className="border-border min-w-0 flex-1 rounded border px-3 py-2 text-sm"
+        />
+        <button
+          type="submit"
+          disabled={loading}
+          className="bg-primary text-primary-foreground rounded px-4 py-2 text-sm font-medium transition-opacity hover:opacity-90 disabled:opacity-60"
+        >
+          {loading ? t('submitting') : t('submit')}
+        </button>
+      </div>
+
+      {/*
+        Honeypot. Bots complete every text input; a human never sees this one, so
+        a non-empty value rejects the request server-side. Positioned off-screen
+        rather than `display:none` — some bots skip hidden inputs — and kept 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" className="text-sm text-red-600">
+          {error}
+        </p>
+      ) : null}
+    </form>
+  );
+}

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

@@ -21,6 +21,9 @@ import type { Content } from 'brainerce';
 // component). Merchant-configured link columns keep plain <a> since their
 // URLs are arbitrary (may be external).
 import { Link } from '@/core/lib/navigation';
+// Client component — the signup posts from the browser, which is also what
+// satisfies the endpoint's browser-Origin requirement.
+import { NewsletterSignup } from './newsletter-signup';
 
 interface SiteFooterProps {
   /** Pre-fetched footer payload (server-side). `null` triggers fallback rendering. */
@@ -64,8 +67,11 @@ export function SiteFooter({ footer, storeName }: SiteFooterProps) {
   if (!data || (columns.length === 0 && !data.copyright && social.length === 0)) {
     return (
       <footer className="border-border bg-muted/30 text-muted-foreground mt-16 border-t py-8 text-sm">
-        <div className="mx-auto max-w-7xl px-4 text-center sm:px-6 lg:px-8">
-          © {year} {brandLabel}. All rights reserved.
+        <div className="mx-auto max-w-7xl space-y-6 px-4 text-center sm:px-6 lg:px-8">
+          <div className="mx-auto max-w-md text-start">
+            <NewsletterSignup />
+          </div>
+          <div>© {year} {brandLabel}. All rights reserved.</div>
         </div>
       </footer>
     );
@@ -108,6 +114,16 @@ export function SiteFooter({ footer, storeName }: SiteFooterProps) {
                 })}
               </div>
             ) : null}
+
+            {/*
+              Newsletter signup. Remove this block if the merchant does not want
+              a mailing list — nothing else depends on it. Confirmed opt-in: the
+              address is not subscribed until the recipient clicks the link they
+              are mailed, which is why the success copy says "check your email".
+            */}
+            <div className="mt-8">
+              <NewsletterSignup />
+            </div>
           </div>
 
           {columns.length > 0 ? (

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

@@ -0,0 +1,173 @@
+'use client';
+
+/**
+ * Back-in-stock alert — "email me when this is back".
+ *
+ * ⛔ THIS IS NOT A NEWSLETTER SIGNUP. `stockAlerts.subscribe()` grants no
+ * marketing consent, creates no customer account, and the person receives
+ * exactly one message: the alert itself, about this item, carrying a link that
+ * stops it. That is why the button says "Notify me" and never "Subscribe" —
+ * and why a shopper who unsubscribed from the store's marketing can still use
+ * it. Never gate it on consent.
+ *
+ * ⛔ RENDER IT ONLY WHERE IT APPLIES. `canOfferStockAlert()` below is the whole
+ * gate. Requests for anything else are silently discarded server-side (the
+ * response is uniform on purpose, so it cannot be used to read a store's stock
+ * levels), which means 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, a product id that does not exist, an item
+ * already in stock, and an address suppressed after a hard bounce. There is
+ * nothing to branch on — render one success state and stop.
+ *
+ * ⛔ DO NOT PROMISE TIMING. Availability is `total - reserved`, so an expiring
+ * cart briefly lifts a sold-out item above zero; the alert waits for stock to
+ * hold, then goes out in waves sized to the units that came back, 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.
+ *
+ * Rate limited to 5 requests / 60s per IP, 25 open alerts per address per store.
+ */
+
+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, and every one of them matters:
+ *
+ *  - the merchant switched the feature off for this storefront
+ *    (`storeInfo.stockAlertsEnabled`, read once at boot);
+ *  - the item is in stock, so there is nothing to wait for;
+ *  - stock is not TRACKED — UNLIMITED never runs out, DISABLED is not for sale
+ *    and no restock changes that;
+ *  - the merchant allows backorders on it, so the storefront can already sell
+ *    it while out of stock 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 and arrives to find their size still gone.
+   */
+  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);
+
+  // Same source the newsletter form uses — <html lang> is set from the active
+  // locale, and passing it is what decides the language of the alert email.
+  // Omit it on a Hebrew storefront and the 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 — the copy stays generic rather than explaining
+      // the rate limit, which would only tell an abuser where the edge is.
+      setError(t('genericError'));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (done) {
+    return (
+      <div className="border-border space-y-1 rounded border p-4">
+        <p className="text-sm font-medium">{t('doneTitle')}</p>
+        <p className="text-sm opacity-70">{t('doneBody')}</p>
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="border-border space-y-2 rounded border p-4">
+      <label htmlFor="back-in-stock-email" className="block text-sm font-medium">
+        {t('title')}
+      </label>
+      <p className="text-sm opacity-70">{t('subtitle')}</p>
+
+      <div className="flex flex-wrap gap-2">
+        <input
+          id="back-in-stock-email"
+          type="email"
+          required
+          autoComplete="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder={t('placeholder')}
+          className="border-border min-w-0 flex-1 rounded border px-3 py-2 text-sm"
+        />
+        <button
+          type="submit"
+          disabled={loading}
+          className="bg-primary text-primary-foreground rounded px-4 py-2 text-sm font-medium transition-opacity hover:opacity-90 disabled:opacity-60"
+        >
+          {loading ? t('submitting') : t('submit')}
+        </button>
+      </div>
+
+      {/*
+        Honeypot. Bots complete every text input; a human never sees this one, so
+        a non-empty value rejects the request server-side. Positioned off-screen
+        rather than `display:none` — some bots skip hidden inputs — and kept 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" className="text-sm text-red-600">
+          {error}
+        </p>
+      ) : null}
+    </form>
+  );
+}