create-brainerce-store 1.88.0 → 1.89.0

package/templates/nextjs/base/src/app/products/page.tsx

@@ -1,19 +1,184 @@
-'use client';
-
-import { Suspense } from 'react';
-import { ProductListing } from '@/ui/product/product-listing';
-import { LoadingSpinner } from '@/ui/shared/loading-spinner';
-
-export default function ProductsPage() {
-  return (
-    <Suspense
-      fallback={
-        <div className="flex min-h-[60vh] items-center justify-center">
-          <LoadingSpinner size="lg" />
-        </div>
-      }
-    >
-      <ProductListing />
-    </Suspense>
-  );
-}
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import Link from 'next/link';
+import type { PublicMetafieldDefinition } from 'brainerce';
+import { getServerClient } from '@/core/lib/brainerce.server';
+import { getRegionId } from '@/core/lib/region.server';
+import {
+  buildProductQuery,
+  isFilterableMetafield,
+  listingSignature,
+  paramSourceFromObject,
+  readListingUrlState,
+  selectedMetafieldsKey,
+} from '@/core/lib/listing-query';
+import { localePath } from '@/core/lib/locale-path';
+import { getServerNamespace } from '@/core/lib/server-messages';
+import { ListingSeedProvider, type ListingSeed } from '@/core/providers/listing-seed';
+import { ProductListing } from '@/ui/product/product-listing';
+
+type Props = {
+  // `locale` exists only on a multi-language storefront (the `[locale]` segment).
+  params: Promise<{ locale?: string }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+};
+
+// Title and description come from the message files in the request locale. They
+// used to be a scaffold-time ternary on `language === 'he'`, which gave every
+// visitor of a multi-language store the default language's copy.
+//
+// Canonical: each page of the catalog is its own canonical (`?page=2` is not a
+// duplicate of page 1, and pointing it there tells Google to drop its products).
+// A filtered, searched or sorted view is a permutation of the same catalog and
+// canonicalizes to the plain listing. The locale prefix is added only for a
+// non-default locale; the middleware 308-redirects `/{default}/x` to `/x`.
+export async function generateMetadata({ params, searchParams }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const state = readListingUrlState(paramSourceFromObject(await searchParams));
+  const seo = await getServerNamespace('seo', locale);
+  const title = seo.products ?? '';
+  const description = seo.productsDescription ?? '';
+
+  const base = localePath(locale, '/products');
+  const isPlainListing =
+    !state.search &&
+    !state.categoryId &&
+    !state.brandId &&
+    !state.tagId &&
+    !state.minPrice &&
+    !state.maxPrice &&
+    state.sortIndex === 0 &&
+    Object.keys(state.metafields).length === 0;
+  const canonical = isPlainListing && state.page > 1 ? `${base}?page=${state.page}` : base;
+
+  return {
+    title,
+    description,
+    alternates: { canonical },
+    // `openGraph` replaces the root layout's object wholesale rather than
+    // merging into it; the store name is added by the title template.
+    openGraph: { title, description, type: 'website' },
+  };
+}
+
+/**
+ * The catalog page. A SERVER component that fetches the page the URL asks for
+ * (search, category, brand, tag, price range, sort, custom-field facets and
+ * `?page=`) and hands it to the client listing, so the initial HTML carries real
+ * products for every one of those URLs. It used to be `'use client'` end to end:
+ * the server sent a spinner and the browser fetched, so a crawler that does not
+ * run JavaScript saw an empty page at the second most important URL on the site.
+ *
+ * Shopper interaction after the first render is unchanged: filters push a new
+ * URL, "Load more" appends, and the client hook fetches for anything the seed
+ * does not answer.
+ */
+export default async function ProductsPage({ params, searchParams }: Props) {
+  const { locale } = await params;
+  const query = await searchParams;
+  const state = readListingUrlState(paramSourceFromObject(query));
+
+  let seed: ListingSeed | null = null;
+  try {
+    const client = await getServerClient(locale);
+    const regionId = await getRegionId();
+
+    // Facets only filter when the store exposes them as filterable, so the
+    // definitions are needed to turn `mf_<key>` into a query, and only when the
+    // URL selected one.
+    let metafieldDefs: PublicMetafieldDefinition[] = [];
+    if (Object.keys(state.metafields).length > 0) {
+      const defs = await client.getPublicMetafieldDefinitions();
+      metafieldDefs = defs.definitions.filter(isFilterableMetafield);
+    }
+    const metafieldsKey = selectedMetafieldsKey(
+      state.metafields,
+      metafieldDefs.map((d) => d.key)
+    );
+    const opts = { regionId, metafieldsKey, page: state.page };
+
+    const result = await client.getProducts(buildProductQuery(state, opts));
+    seed = {
+      products: result.data,
+      page: state.page,
+      totalPages: result.meta.totalPages,
+      total: result.meta.total,
+      signature: listingSignature(state, opts),
+      metafieldDefs,
+    };
+  } catch {
+    // Non-fatal: the client hook fetches the same query itself.
+    seed = null;
+  }
+
+  // No `<Suspense>` around the listing, deliberately. The listing reads the URL
+  // through `useSearchParams`, which only needs a boundary when a route is
+  // prerendered statically; this page is dynamic (it reads `searchParams`), so
+  // there is nothing to bail out of. The wrapper was not neutral: in the base
+  // design it made the server flush a spinner fallback and stream the real grid
+  // after it, which is the opposite of what the seed is for.
+  // A page past the end of the result set is not a page. Rendering it empty with
+  // its own canonical hands crawlers an endless supply of soft-404 URLs
+  // (`?page=99`, `?page=100`, ...). Only when the query answered, never when the
+  // fetch failed (then `seed` is null and the client hook tries again).
+  if (seed && state.page > 1 && seed.products.length === 0) notFound();
+
+  // Crawlable pagination. "Load more" is a button, so without real links nothing
+  // on the page leads to `?page=2`, and a crawler that does not run JavaScript
+  // can only reach page 2+ of the catalog by guessing the URL. These are plain
+  // `<a>` links rendered on the server, keeping whatever filters the shopper has
+  // chosen; shoppers keep using "Load more".
+  const pageHref = (target: number): string => {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      const first = Array.isArray(value) ? value[0] : value;
+      if (first !== undefined && key !== 'page') params.set(key, first);
+    }
+    if (target > 1) params.set('page', String(target));
+    const qs = params.toString();
+    return `${localePath(locale, '/products')}${qs ? `?${qs}` : ''}`;
+  };
+  const strings = seed && seed.totalPages > 1 ? await getServerNamespace('seo', locale) : null;
+
+  return (
+    <>
+      <ListingSeedProvider listing={seed}>
+        <ProductListing />
+      </ListingSeedProvider>
+      {seed && strings ? (
+        <nav
+          aria-label={strings.pagination}
+          className="mx-auto flex max-w-7xl items-center justify-center gap-6 px-4 pb-10 text-sm sm:px-6 lg:px-8"
+        >
+          {seed.page > 1 ? (
+            <Link
+              href={pageHref(Math.min(seed.page - 1, seed.totalPages))}
+              rel="prev"
+              className="text-muted-foreground hover:text-foreground inline-flex items-center gap-1 transition-colors"
+            >
+              <span aria-hidden="true" className="rtl:rotate-180">
+                ←
+              </span>
+              {strings.previousPage}
+            </Link>
+          ) : null}
+          <span className="text-muted-foreground">
+            {seed.page} / {seed.totalPages}
+          </span>
+          {seed.page < seed.totalPages ? (
+            <Link
+              href={pageHref(seed.page + 1)}
+              rel="next"
+              className="text-muted-foreground hover:text-foreground inline-flex items-center gap-1 transition-colors"
+            >
+              {strings.nextPage}
+              <span aria-hidden="true" className="rtl:rotate-180">
+                →
+              </span>
+            </Link>
+          ) : null}
+        </nav>
+      ) : null}
+    </>
+  );
+}

package/templates/nextjs/base/src/components/auth/oauth-buttons.tsx

@@ -3,6 +3,7 @@
 import { useState, useEffect } from 'react';
 import type { CustomerOAuthProvider } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
+import { readReferralCookie } from '@/core/lib/referral';
 import { useTranslations } from '@/core/lib/translations';
 import { cn } from '@/core/lib/utils';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
@@ -106,7 +107,14 @@ export function OAuthButtons({ className }: OAuthButtonsProps) {
       setFailedProvider(null);
       const client = getClient();
       const redirectUrl = window.location.origin + '/api/auth/oauth-callback';
-      const result = await client.getOAuthAuthorizeUrl(provider, { redirectUrl });
+      // Carry the captured ?ref= code through the round trip. The backend
+      // applies it only if this sign-in creates the account, so passing it on
+      // every click is safe; without it a Google sign-up loses the referral.
+      const referralCode = readReferralCookie();
+      const result = await client.getOAuthAuthorizeUrl(provider, {
+        redirectUrl,
+        ...(referralCode ? { referralCode } : {}),
+      });
       window.location.href = result.authorizationUrl;
     } catch (err) {
       // The 400 body is a rule for the merchant (`redirect_not_allowed` and

package/templates/nextjs/base/src/components/checkout/payment-step.tsx

@@ -111,6 +111,10 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
   const [preloadedSdk, setPreloadedSdk] = useState<PaymentClientSdk | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  // True when the server refused this checkout as "already being processed"
+  // (409 `checkout_claim_failed`). Retrying the same checkout cannot succeed, so the error box
+  // offers a fresh checkout instead of a dead end.
+  const [canRestart, setCanRestart] = useState(false);
   const [sdkReady, setSdkReady] = useState(false);
   // Set by the Cardcom OpenFields embed page via `brainerce:resize` postMessage.
   // Presence of this value is how we distinguish our own compact embed page
@@ -454,7 +458,21 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
         // from the provider SDK on a different path and keep their own wording,
         // which is the part a shopper can actually act on.
         console.error('[checkout] could not start payment', err);
-        setError(t('paymentUnavailable'));
+        if (
+          err instanceof BrainerceError &&
+          err.statusCode === 409 &&
+          (err.details as { code?: string } | undefined)?.code === 'checkout_claim_failed'
+        ) {
+          // The checkout is locked by an earlier attempt (a lost response, a
+          // reload) and will never accept another intent. A new checkout from the
+          // same cart is the way forward, not "contact the store". Only THIS 409:
+          // a provider's own 409 (e.g. `provider_not_ready`, KYC pending) would hit
+          // the same wall on a fresh checkout, so it keeps the generic message.
+          setCanRestart(true);
+          setError(t('paymentSessionStuck'));
+        } else {
+          setError(t('paymentUnavailable'));
+        }
         return null;
       })
       .finally(() => setLoading(false));
@@ -656,6 +674,17 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
         <p className="text-muted-foreground mx-auto max-w-md text-sm">
           {isNotConfigured ? t('paymentNotConfiguredDesc') : error}
         </p>
+        {canRestart && (
+          <button
+            type="button"
+            // Same page without `?checkout_id=`: the bare /checkout link opens a
+            // fresh checkout for the cart and never resumes a locked one.
+            onClick={() => window.location.assign(window.location.pathname)}
+            className="bg-primary text-primary-foreground mt-6 inline-flex items-center rounded px-6 py-3 text-sm font-medium transition-opacity hover:opacity-90"
+          >
+            {t('startNewCheckout')}
+          </button>
+        )}
       </div>
     );
   }

package/templates/nextjs/base/src/components/seo/article-json-ld.tsx

@@ -8,6 +8,11 @@ interface ArticleJsonLdProps {
   url: string;
   /** Store display name — feeds Article.publisher (and the author fallback). */
   organizationName?: string;
+  /**
+   * The BreadcrumbList trail, absolute URLs, last item = this post. Names come
+   * from the message files in the request locale, never hardcoded here.
+   */
+  breadcrumbs: Array<{ name: string; url: string }>;
 }
 
 /**
@@ -16,7 +21,12 @@ interface ArticleJsonLdProps {
  * Uses the SDK builders for the schema shape, but renders the <script> here so
  * we can attach the CSP nonce (the SDK's jsonLdScriptProps can't).
  */
-export async function ArticleJsonLd({ post, url, organizationName }: ArticleJsonLdProps) {
+export async function ArticleJsonLd({
+  post,
+  url,
+  organizationName,
+  breadcrumbs,
+}: ArticleJsonLdProps) {
   const nonce = await getNonce();
   const baseUrl = await getCanonicalSiteUrl();
 
@@ -26,11 +36,7 @@ export async function ArticleJsonLd({ post, url, organizationName }: ArticleJson
     organizationName,
   });
 
-  const breadcrumbJsonLd = buildBreadcrumbJsonLd([
-    { name: 'Home', url: baseUrl || '/' },
-    { name: 'Blog', url: `${baseUrl}/blog` },
-    { name: post.title, url },
-  ]);
+  const breadcrumbJsonLd = buildBreadcrumbJsonLd(breadcrumbs);
 
   return (
     <>

package/templates/nextjs/base/src/components/seo/category-json-ld.tsx

@@ -6,6 +6,12 @@ import { getCanonicalSiteUrl } from '@/core/lib/site-url';
 interface CategoryJsonLdProps {
   category: CategoryDetail;
   url: string;
+  /**
+   * The BreadcrumbList trail, absolute URLs, last item = this category. Pass the
+   * SAME items the page renders as its visible breadcrumb. Names come from the
+   * message files, never hardcoded here.
+   */
+  breadcrumbs: Array<{ name: string; url: string }>;
 }
 
 /**
@@ -16,21 +22,14 @@ interface CategoryJsonLdProps {
  * Uses the SDK builders for the schema shape, but renders the <script> here so
  * we can attach the CSP nonce (the SDK's jsonLdScriptProps can't).
  */
-export async function CategoryJsonLd({ category, url }: CategoryJsonLdProps) {
+export async function CategoryJsonLd({ category, url, breadcrumbs }: CategoryJsonLdProps) {
   const nonce = await getNonce();
   const baseUrl = await getCanonicalSiteUrl();
 
   const collectionJsonLd = buildCollectionPageJsonLd(category, { siteUrl: baseUrl, path: url });
 
-  // Breadcrumb: Home → ancestor categories → this category.
-  const crumbs: Array<{ name: string; url: string }> = [{ name: 'Home', url: baseUrl || '/' }];
-  for (const ancestor of category.breadcrumb) {
-    if (ancestor.slug) {
-      crumbs.push({ name: ancestor.name, url: `${baseUrl}/category/${ancestor.slug}` });
-    }
-  }
-  crumbs.push({ name: category.name, url });
-  const breadcrumbJsonLd = buildBreadcrumbJsonLd(crumbs);
+  // Breadcrumb: Home → ancestor categories → this category, as the page shows it.
+  const breadcrumbJsonLd = buildBreadcrumbJsonLd(breadcrumbs);
 
   return (
     <>

package/templates/nextjs/base/src/components/seo/product-json-ld.tsx

@@ -10,6 +10,13 @@ interface ProductJsonLdProps {
   currency?: string;
   /** From `storeInfo.shipping` — real flat-rate/free zones only. Omitted entirely when unset, never fabricated. */
   shipping?: ShippingSummaryEntry[];
+  /**
+   * The BreadcrumbList trail, absolute URLs, last item = this product. Pass the
+   * SAME items the page renders as its visible breadcrumb: structured data that
+   * names a different path than the page shows is a mismatch Google can flag.
+   * Names come from the message files, never hardcoded here.
+   */
+  breadcrumbs: Array<{ name: string; url: string }>;
 }
 
 /**
@@ -23,7 +30,13 @@ interface ProductJsonLdProps {
  * The <script> is rendered locally only to attach the CSP nonce (the SDK's
  * jsonLdScriptProps can't).
  */
-export async function ProductJsonLd({ product, url, currency, shipping }: ProductJsonLdProps) {
+export async function ProductJsonLd({
+  product,
+  url,
+  currency,
+  shipping,
+  breadcrumbs,
+}: ProductJsonLdProps) {
   // Defer to the shared server helper so the env-var + USD fallback chain
   // lives in exactly one place across all server-side currency reads.
   const resolvedCurrency = resolveCurrency(null, currency);
@@ -37,11 +50,7 @@ export async function ProductJsonLd({ product, url, currency, shipping }: Produc
     shipping,
   });
 
-  const breadcrumbJsonLd = buildBreadcrumbJsonLd([
-    { name: 'Home', url: baseUrl || '/' },
-    { name: 'Products', url: `${baseUrl}/products` },
-    { name: product.name, url },
-  ]);
+  const breadcrumbJsonLd = buildBreadcrumbJsonLd(breadcrumbs);
 
   // FAQPage from the product's Q&A — null (no script) when the product has
   // none. The visible FAQ section on the PDP renders the SAME pairs; this is

package/templates/nextjs/base/src/components/seo/product-og-meta.tsx

@@ -0,0 +1,46 @@
+interface ProductOgMetaProps {
+  /** Positive price, already formatted to two decimals; null when it cannot be determined. */
+  priceAmount: string | null;
+  currency: string;
+  inStock: boolean;
+  brandName?: string;
+}
+
+/**
+ * Open Graph `product` object: the type tag plus the price, availability, condition
+ * and brand tags that Facebook, Pinterest and Google Merchant Center read off a
+ * product page.
+ *
+ * Rendered as real `<meta property="...">` elements instead of through Next's
+ * `metadata` for two reasons, both about what ends up in the HTML:
+ *  - `openGraph.type` only accepts a fixed list of values and `product` is not on
+ *    it, so the metadata API cannot emit `og:type: product`.
+ *  - `metadata.other` renders `<meta name="...">`, and these tags are read from
+ *    `property=`. Emitting them as `name=` looks right in the source and is
+ *    ignored by the crawlers they exist for.
+ * React hoists a `<meta>` rendered in a component into `<head>`.
+ *
+ * The product page must NOT also set `openGraph.type`, or the page carries two
+ * `og:type` tags.
+ *
+ * Skips the price pair entirely when no positive amount is known, rather than
+ * shipping "0", which turns every link preview into a free product.
+ */
+export function ProductOgMeta({ priceAmount, currency, inStock, brandName }: ProductOgMetaProps) {
+  return (
+    <>
+      <meta property="og:type" content="product" />
+      {priceAmount ? (
+        <>
+          <meta property="og:price:amount" content={priceAmount} />
+          <meta property="og:price:currency" content={currency} />
+          <meta property="product:price:amount" content={priceAmount} />
+          <meta property="product:price:currency" content={currency} />
+        </>
+      ) : null}
+      <meta property="product:availability" content={inStock ? 'in stock' : 'out of stock'} />
+      <meta property="product:condition" content="new" />
+      {brandName ? <meta property="product:brand" content={brandName} /> : null}
+    </>
+  );
+}

package/templates/nextjs/base/src/core/hooks/use-home-data.ts

@@ -1,8 +1,10 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import type { Product } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
+import { HOME_FEATURED_LIMIT } from '@/core/lib/listing-query';
+import { useHomeSeed } from '@/core/providers/listing-seed';
 import { useRegion } from '@/core/providers/store-provider';
 
 export interface UseHomeDataResult {
@@ -15,6 +17,12 @@ export interface UseHomeDataResult {
 /**
  * Homepage data: the featured product grid.
  *
+ * The server fetches the first render's products (`app/page.tsx` wraps the page
+ * in `<ListingSeedProvider home={...}>`), so the initial HTML carries real
+ * products. This hook then starts from that seed and only fetches when the seed
+ * does not apply, which is when the shopper's region differs from the one the
+ * server priced in, or when no seed was provided.
+ *
  * Discount banners are deliberately NOT fetched here. They render below the
  * header on every page, so the root layout fetches them server-side and hands
  * them to `<DiscountBannerStrip>`. Fetching them again on the home page would
@@ -23,21 +31,33 @@ export interface UseHomeDataResult {
  * Pure data/behavior — rendering lives in `ui/home/`.
  */
 export function useHomeData(): UseHomeDataResult {
-  const [products, setProducts] = useState<Product[]>([]);
-  const [loading, setLoading] = useState(true);
+  const seed = useHomeSeed();
+  const [products, setProducts] = useState<Product[]>(seed?.products ?? []);
+  const [loading, setLoading] = useState(!seed);
   // ⛔ Every product read carries the region, or the featured grid quotes the
   // default region's currency to a shopper the product page then prices
   // differently. `undefined` on a store with no regions, and the SDK omits
   // the param, so a single-region store behaves exactly as before.
   const { regionId } = useRegion();
 
+  // The region the seed was priced in, or null once it no longer applies. A ref
+  // rather than a flag that is flipped on first use, so React's dev-only double
+  // effect run cannot spend the seed and then fetch anyway.
+  const seededRegion = useRef<{ id: string | undefined } | null>(
+    seed ? { id: seed.regionId } : null
+  );
+
   useEffect(() => {
+    if (seededRegion.current && seededRegion.current.id === regionId) return;
+    seededRegion.current = null;
+
     async function load() {
       try {
+        setLoading(true);
         const client = getClient();
         const [productsRes] = await Promise.allSettled([
           client.getProducts({
-            limit: 8,
+            limit: HOME_FEATURED_LIMIT,
             sortBy: 'createdAt',
             sortOrder: 'desc',
             ...(regionId ? { regionId } : {}),