@forgecart/cli 2.202610052310.0 → 2.202610071755.0

package/templates/storefront-shadcn/src/app/products/[slug]/page.tsx

@@ -0,0 +1,317 @@
+import type { Metadata } from 'next';
+import { notFound, permanentRedirect } from 'next/navigation';
+import { connection } from 'next/server';
+import { Suspense, cache } from 'react';
+
+import { ProductPurchase } from '../../../components/ProductPurchase';
+import { LocaleLink } from '../../../components/LocaleLink';
+import { Skeleton } from '../../../components/ui/skeleton';
+import { getAssetAlt } from '../../../lib/asset-alt';
+import {
+  getProductBySlug,
+  getSellingPlanGroupsForVariant,
+  type ProductWithSeo,
+  type SellingPlanGroup,
+} from '../../../lib/forgecart';
+import type { LocaleBinding } from '../../../lib/locale/localized-path';
+import { getRequestLocale } from '../../../lib/locale/request-binding';
+import { buildAlternates } from '../../../lib/seo/alternates';
+import {
+  breadcrumbJsonLd,
+  productJsonLd,
+  serializeJsonLd,
+  type JsonLdNode,
+} from '../../../lib/seo/json-ld';
+import { entityMetadata, routeMetadata } from '../../../lib/seo/metadata';
+import { routeRobots, type RouteSearchParams } from '../../../lib/seo/noindex';
+import { getPublicOrigin } from '../../../lib/seo/public-origin';
+import { productPathsByLocale, resolveProductPath } from '../../../lib/seo/resolve-path';
+
+/**
+ * The trail, once — rendered as the visible breadcrumbs AND as the
+ * `BreadcrumbList` a crawler reads. Two lists would be two claims about where
+ * this page sits, and nothing in the template would notice them diverging.
+ */
+const BREADCRUMB_TRAIL: readonly { name: string; path: string }[] = [
+  { name: 'Home', path: '/' },
+  { name: 'Products', path: '/products' },
+];
+
+/**
+ * One product read per request, shared by `generateMetadata` and the page.
+ *
+ * Next invokes them as separate calls, so without React's request cache the
+ * slug law would run against two independent fetches — and a product renamed
+ * between them would emit metadata for one address while redirecting to
+ * another.
+ */
+const productForRequest = cache(async (slug: string) => getProductBySlug(slug));
+
+// PROGRESSIVE PRE-RENDERING: static shell; the data sections below are
+// per-request holes streamed inside their Suspense boundaries
+// (see next.config.js for why every route is request-rendered).
+
+/**
+ * Indexability for a product URL comes from the same resolution the page acts
+ * on, through the shared request cache — so the tag and the status can never
+ * disagree about what this URL is.
+ *
+ * Two content-level refusals ride here that no route rule could know: a
+ * FALLBACK copy (this language has no real content, so indexing it would put
+ * near-duplicate text in competition with the language that does) and the
+ * merchant's own `indexable: false`. Redirect and notFound need no directive —
+ * their metadata is discarded with the response body.
+ *
+ * Like an ACF page's (`/pages/<route>`, #1375), this route's title, description
+ * and social image are the MERCHANT's rather than the template's: they come
+ * from the per-language SEO sidecar through `entityMetadata`, already resolved
+ * into the request's language by the shop API, so a German product page
+ * carries a German title without this file knowing anything about translation.
+ */
+export async function generateMetadata({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<RouteSearchParams>;
+}): Promise<Metadata> {
+  const [{ slug }, resolvedSearchParams] = await Promise.all([params, searchParams]);
+  const { binding, shopName, channelResolved } = await getRequestLocale();
+  const product = await productForRequest(slug);
+  const resolution = resolveProductPath({ requestedSlug: slug, product, binding });
+  const entity = product ? entityMetadata(product, binding.locale) : null;
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: `/products/${slug}`,
+    searchParams: resolvedSearchParams,
+    // Unlike a structural route, a product earns its alternates per language:
+    // the map is the intersection of "has a slug" and "has content", so an
+    // untranslated language never appears. `buildAlternates` then returns
+    // undefined for a fallback copy — no canonical, no hreflang — because a
+    // derived page has no address of its own to claim and must not be pulled
+    // into a reciprocal set it is not a member of. An absent product yields an
+    // empty map, which lands in that same arm rather than needing its own.
+    pathsByLocale: product ? productPathsByLocale(product) : {},
+    title: entity?.title ?? null,
+    description: entity?.description,
+    socialImage: entity?.socialImage,
+    contentIndexable: resolution.kind === 'ok' ? resolution.indexable : false,
+  });
+}
+
+/**
+ * Product detail (Blueprint `pages/product-detail`): identity block ordering —
+ * media, then title, then price/variants/CTA (ProductPurchase owns those),
+ * then the long-form description. Breadcrumbs replace the bare back-link so
+ * shoppers keep their place in the catalog.
+ */
+// Next.js 15: route params are delivered as a Promise.
+/**
+ * The slug law runs in the page SHELL, above the Suspense boundary, and that
+ * placement is the whole correctness of the route's status codes.
+ *
+ * `notFound()` and `permanentRedirect()` can only set a status where Next
+ * assigns one. Raised from inside a boundary — as the product lookup used to
+ * be — the shell has already flushed with a 200 and the throw resolves as
+ * client-rendered content instead: the response is a **200 carrying a
+ * not-found page**. A crawler drops a real 404 and INDEXES a soft one, so an
+ * unknown slug would have put an error page into the index under a URL that
+ * will never hold content. (Measured: `/products/no-such-product` answered 200
+ * before this moved.)
+ *
+ * The cost is that the product read is no longer streamed — but it is the one
+ * thing this page IS, so a skeleton bought nothing while the only content
+ * loaded. The genuinely secondary read (per-variant selling plans) stays in the
+ * boundary below, which is what streaming is for.
+ */
+export default async function ProductDetailPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<RouteSearchParams>;
+}) {
+  const { binding } = await getRequestLocale();
+  const [{ slug }, resolvedSearchParams] = await Promise.all([params, searchParams]);
+  const product = await productForRequest(slug);
+  const resolution = resolveProductPath({ requestedSlug: slug, product, binding });
+
+  // `product === null` IS the resolution's notFound arm — spelled out rather
+  // than matched on `resolution.kind` so TypeScript narrows `product` for the
+  // render below (`notFound()` returns never). Matching the kind would leave it
+  // nullable and force a cast that asserts what the law already guarantees.
+  if (product === null) notFound();
+  if (resolution.kind === 'redirect') permanentRedirect(resolution.to);
+
+  return (
+    <div className="space-y-8">
+      {structuredData(product, binding, slug, resolvedSearchParams, resolution).map((node) => (
+        <script
+          key={node['@type']}
+          type="application/ld+json"
+          // The ONE way to put JSON-LD in a document; `serializeJsonLd` escapes
+          // `<`, so a description carrying `</script>` cannot close the element.
+          dangerouslySetInnerHTML={{ __html: serializeJsonLd(node) }}
+        />
+      ))}
+      <Suspense fallback={<DetailSkeleton />}>
+        <ProductDetail product={product} locale={binding} />
+      </Suspense>
+    </div>
+  );
+}
+
+/**
+ * The structured data this page is entitled to emit — empty whenever it is not.
+ *
+ * Gated on the SAME `routeRobots` the metadata uses, because a page telling
+ * crawlers to ignore it while handing them a machine-readable description of
+ * its contents is making two opposite claims at once. `undefined` from that
+ * call is the one mechanism's way of saying "this is a real, indexable
+ * address", and it already covers the fallback copy, the merchant's own
+ * `indexable: false`, query-state views and the missing public origin.
+ *
+ * The origin is read ONCE and handed to both claims this function makes — the
+ * canonical `buildAlternates` derives, and the breadcrumb item URLs — so the
+ * two can never name different hosts. Its null arm is what narrows it to a
+ * string for those URLs; it cannot be taken here, because no-origin is one of
+ * the reasons the gate above would already have closed.
+ */
+function structuredData(
+  product: ProductWithSeo,
+  binding: LocaleBinding,
+  slug: string,
+  searchParams: RouteSearchParams,
+  resolution: ReturnType<typeof resolveProductPath>,
+): JsonLdNode[] {
+  const contentIndexable = resolution.kind === 'ok' ? resolution.indexable : false;
+  if (routeRobots(`/products/${slug}`, searchParams, contentIndexable) !== undefined) return [];
+
+  const publicOrigin = getPublicOrigin();
+  const alternates = buildAlternates({
+    binding,
+    pathsByLocale: productPathsByLocale(product),
+    publicOrigin,
+  });
+  if (!alternates || publicOrigin === null) return [];
+
+  return [
+    productJsonLd({
+      name: product.name,
+      description: product.description,
+      image: product.featuredAsset?.preview,
+      canonical: alternates.canonical,
+      variants: product.variants,
+    }),
+    breadcrumbJsonLd({
+      binding,
+      publicOrigin,
+      leafName: product.name,
+      trail: BREADCRUMB_TRAIL,
+    }),
+  ];
+}
+
+async function ProductDetail({
+  product,
+  locale: binding,
+}: {
+  product: ProductWithSeo;
+  locale: LocaleBinding;
+}) {
+  // Request-time hole: streamed inside its Suspense boundary.
+  await connection();
+
+  // Subscription selling plans are eligible per variant, so fetch the groups for
+  // each of the product's variants (in parallel) and pass a variantId -> groups
+  // map to the client purchase control. Variants with no plans get the plain
+  // one-time add-to-cart path.
+  const planGroupsByVariant: Record<string, SellingPlanGroup[]> = Object.fromEntries(
+    await Promise.all(
+      product.variants.map(
+        async (variant): Promise<[string, SellingPlanGroup[]]> => [
+          variant.id,
+          await getSellingPlanGroupsForVariant(variant.id),
+        ],
+      ),
+    ),
+  );
+
+  return (
+    <>
+      <nav aria-label="Breadcrumb" className="text-sm text-muted-foreground">
+        <ol className="flex flex-wrap items-center gap-1.5 break-words">
+          {BREADCRUMB_TRAIL.map((crumb) => (
+            <li key={crumb.path} className="inline-flex items-center gap-1.5">
+              <LocaleLink
+                href={crumb.path}
+                locale={binding}
+                className="transition-colors hover:text-foreground"
+              >
+                {crumb.name}
+              </LocaleLink>
+              <span aria-hidden="true">/</span>
+            </li>
+          ))}
+          <li className="inline-flex items-center">
+            <span aria-current="page" className="text-foreground">
+              {product.name}
+            </span>
+          </li>
+        </ol>
+      </nav>
+
+      <div className="grid gap-8 lg:grid-cols-2 lg:gap-12">
+        <figure className="aspect-square overflow-hidden rounded-xl border bg-muted lg:sticky lg:top-24 lg:self-start">
+          {product.featuredAsset ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={product.featuredAsset.preview}
+              alt={getAssetAlt(product.featuredAsset)}
+              className="h-full w-full object-cover"
+            />
+          ) : (
+            <div className="flex h-full w-full items-center justify-center text-sm text-muted-foreground">
+              No image
+            </div>
+          )}
+        </figure>
+
+        <div className="space-y-6">
+          <h1 className="text-3xl font-bold tracking-tight text-balance">{product.name}</h1>
+
+          {/* Pick a variant (Size/Color) -> price + purchase options + add-to-cart. */}
+          <ProductPurchase product={product} planGroupsByVariant={planGroupsByVariant} />
+
+          {product.description && (
+            <section aria-label="Product description" className="border-t pt-6">
+              <div
+                className="max-w-none text-sm leading-relaxed text-muted-foreground"
+                // Product descriptions may contain rich text from the dashboard.
+                dangerouslySetInnerHTML={{ __html: product.description }}
+              />
+            </section>
+          )}
+        </div>
+      </div>
+    </>
+  );
+}
+
+function DetailSkeleton() {
+  return (
+    <div aria-busy="true">
+      <Skeleton className="h-4 w-56" />
+      <div className="mt-8 grid gap-8 lg:grid-cols-2 lg:gap-12">
+        <Skeleton className="aspect-square w-full" />
+        <div className="space-y-4">
+          <Skeleton className="h-9 w-3/4" />
+          <Skeleton className="h-24 w-full" />
+          <Skeleton className="h-12 w-full" />
+        </div>
+      </div>
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/app/products/page.tsx

@@ -0,0 +1,107 @@
+import type { Metadata } from 'next';
+import { connection } from 'next/server';
+import { Suspense } from 'react';
+
+import { ProductCard } from '../../components/ProductCard';
+import { Skeleton } from '../../components/ui/skeleton';
+import { getProducts } from '../../lib/forgecart';
+import type { LocaleBinding } from '../../lib/locale/localized-path';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { staticPathsByLocale } from '../../lib/seo/alternates';
+import { routeMetadata } from '../../lib/seo/metadata';
+import type { RouteSearchParams } from '../../lib/seo/noindex';
+
+/**
+ * The catalog is indexable; a SORTED catalog is the same products in another
+ * order, so `?sort=` is a view of this page rather than a page of its own.
+ *
+ * The title is the template's own chrome, in English, exactly like this page's
+ * `<h1>`: structural surfaces are not translated content, and inventing a
+ * translation layer for them here would put a second, weaker source of truth
+ * beside the shop API's. The pages whose titles a merchant actually cares
+ * about — products and the merchant's own ACF pages — take theirs from the
+ * localized SEO sidecar.
+ */
+export async function generateMetadata({
+  searchParams,
+}: {
+  searchParams: Promise<RouteSearchParams>;
+}): Promise<Metadata> {
+  const [resolvedSearchParams, { binding, languageCodes, shopName, channelResolved }] =
+    await Promise.all([searchParams, getRequestLocale()]);
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: '/products',
+    pathsByLocale: staticPathsByLocale(languageCodes, '/products'),
+    searchParams: resolvedSearchParams,
+    title: 'All products',
+  });
+}
+
+// PROGRESSIVE PRE-RENDERING: static shell; the data sections below are
+// per-request holes streamed inside their Suspense boundaries
+// (see next.config.js for why every route is request-rendered).
+
+/**
+ * Catalog — the browse grid. The header carries the count as orientation
+ * (Blueprint listing guidance: state scope up front); cards do the visual
+ * lifting, the grid stays quiet.
+ */
+export default async function ProductsPage() {
+  const { binding } = await getRequestLocale();
+  return (
+    <div className="space-y-8">
+      <Suspense fallback={<CatalogSkeleton />}>
+        <Catalog locale={binding} />
+      </Suspense>
+    </div>
+  );
+}
+
+async function Catalog({ locale }: { locale: LocaleBinding }) {
+  // Request-time hole: streamed inside its Suspense boundary.
+  await connection();
+  const { items, totalItems } = await getProducts({ take: 24 });
+
+  return (
+    <>
+      <header className="flex flex-wrap items-baseline justify-between gap-3 border-b pb-6">
+        <h1 className="text-3xl font-bold tracking-tight">All products</h1>
+        <span className="text-sm text-muted-foreground">
+          {totalItems} {totalItems === 1 ? 'item' : 'items'}
+        </span>
+      </header>
+
+      {items.length === 0 ? (
+        <p className="text-muted-foreground">
+          No products yet — add your first product in the dashboard and it appears here.
+        </p>
+      ) : (
+        <div className="grid grid-cols-2 gap-4 sm:grid-cols-3 sm:gap-6 lg:grid-cols-4">
+          {items.map((product) => (
+            <ProductCard key={product.id} product={product} locale={locale} />
+          ))}
+        </div>
+      )}
+    </>
+  );
+}
+
+function CatalogSkeleton() {
+  return (
+    <div aria-busy="true">
+      <header className="flex items-baseline justify-between gap-3 border-b pb-6">
+        <h1 className="text-3xl font-bold tracking-tight">All products</h1>
+        <Skeleton className="h-4 w-16" />
+      </header>
+      <div className="mt-8 grid grid-cols-2 gap-4 sm:grid-cols-3 sm:gap-6 lg:grid-cols-4">
+        <Skeleton className="aspect-square w-full" />
+        <Skeleton className="aspect-square w-full" />
+        <Skeleton className="aspect-square w-full" />
+        <Skeleton className="aspect-square w-full" />
+      </div>
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/app/register/page.tsx

@@ -0,0 +1,54 @@
+import type { Metadata } from 'next';
+
+import { RegisterForm } from '../../components/account/RegisterForm';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { routeMetadata } from '../../lib/seo/metadata';
+
+/**
+ * `/register` — where a shopper creates an account (#1471).
+ *
+ * The page renders a form and nothing else: it asks the shop API nothing on
+ * GET, so unlike `/verify` there is no request-time hole to stream, and unlike
+ * `/reset-password` there is no token in the URL to read. Everything that
+ * happens here happens on the SUBMIT, over the shopper's own websocket.
+ *
+ * Unlike the two account-LINK routes, this one IS locale-prefixable — a
+ * shopper addresses it, from a link on this storefront, rather than receiving
+ * it in a mail — so `register` is deliberately absent from the grammar's
+ * unprefixed set and `/de/register` serves the German render.
+ */
+
+const PAGE_TITLE = 'Create an account';
+
+/**
+ * Noindex via `NOINDEX_PATHS`: a form with no content of its own competes with
+ * nothing, and it is the same posture `/cart` and `/checkout` take.
+ *
+ * No alternates, despite the route existing in every language. Hreflang is a
+ * claim about which address of a cluster a crawler should prefer, and a page
+ * that has just declined to be indexed at all has no such preference to state;
+ * the empty map is what makes `buildAlternates` withhold the claim rather than
+ * this page hand-rolling a robots value of its own.
+ */
+export async function generateMetadata(): Promise<Metadata> {
+  const { binding, shopName, channelResolved } = await getRequestLocale();
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: '/register',
+    pathsByLocale: {},
+    title: PAGE_TITLE,
+  });
+}
+
+export default async function RegisterPage() {
+  const { binding } = await getRequestLocale();
+
+  return (
+    <div className="mx-auto max-w-xl space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight">{PAGE_TITLE}</h1>
+      <RegisterForm locale={binding} />
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/app/reset-password/page.tsx

@@ -0,0 +1,60 @@
+import type { Metadata } from 'next';
+
+import { RequestPasswordResetForm } from '../../components/account/RequestPasswordResetForm';
+import { ResetPasswordForm } from '../../components/account/ResetPasswordForm';
+import { readLinkToken } from '../../lib/account/account-link';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { routeMetadata } from '../../lib/seo/metadata';
+import type { RouteSearchParams } from '../../lib/seo/noindex';
+
+/**
+ * `/reset-password` — the page the platform's password-reset e-mail links to,
+ * and the place a shopper asks for that e-mail in the first place (#1472).
+ *
+ * ONE route, two modes, chosen by the URL's token:
+ *
+ *  - `?token=…` — set a new password. The token is spent by the SUBMIT, never
+ *    by the render: unlike verification, the shopper has something to type, so
+ *    consuming the token on arrival would burn it before they got the chance.
+ *  - no token — ask for a link. A shopper who lets one expire has nowhere else
+ *    to go, and sending them back to the mail that is already stale is a dead
+ *    end; the same address they were mailed at is all this form needs.
+ *
+ * Both modes render forms and nothing else, so unlike `/verify` there is no
+ * request-time hole to stream — the page reads the request and renders.
+ */
+
+const PAGE_TITLE = 'Reset your password';
+
+/** Noindex, and no alternates — for the reasons `/verify`'s metadata states. */
+export async function generateMetadata(): Promise<Metadata> {
+  const { binding, shopName, channelResolved } = await getRequestLocale();
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: '/reset-password',
+    pathsByLocale: {},
+    title: PAGE_TITLE,
+  });
+}
+
+export default async function ResetPasswordPage({
+  searchParams,
+}: {
+  searchParams: Promise<RouteSearchParams>;
+}) {
+  const [params, { binding }] = await Promise.all([searchParams, getRequestLocale()]);
+  const token = readLinkToken(params);
+
+  return (
+    <div className="mx-auto max-w-xl space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight">{PAGE_TITLE}</h1>
+      {token === null ? (
+        <RequestPasswordResetForm locale={binding} />
+      ) : (
+        <ResetPasswordForm token={token} locale={binding} />
+      )}
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/app/robots.ts

@@ -0,0 +1,69 @@
+import type { MetadataRoute } from 'next';
+
+import { NOINDEX_PATHS, NOINDEX_QUERY_KEYS } from '../lib/seo/noindex';
+import { getPublicOrigin } from '../lib/seo/public-origin';
+
+/**
+ * `robots.txt` (#1347, epic launch#54 W1-9) — the crawler-facing half of the
+ * indexability contract in `lib/seo/noindex.ts`.
+ *
+ * FORCE-DYNAMIC, and that is load-bearing rather than cautious. Next
+ * pre-renders metadata routes at build time by default, and a storefront is
+ * built once then run with its per-channel environment supplied afterwards. A
+ * build-time answer would freeze the BUILDER's environment — which never has a
+ * channel's public origin — into `Disallow: /` for every store shipped from
+ * that image, permanently, with no way to correct it short of a rebuild. The
+ * scaffold is frozen at provisioning time (#1041), so "permanently" is literal.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Infrastructure routes that are never a destination for a human or a crawler:
+ * the tracking relay, the error beacon, the SDK proxy and the health probe.
+ *
+ * Deliberately NOT derived from the locale grammar's `UNPREFIXED_FIRST_SEGMENTS`
+ * despite the overlap. That set answers "which first segments are not a
+ * language?" and correctly contains `sitemap.xml`, `robots.txt`, `_next` and
+ * `favicon.ico` — every one of which a crawler MUST be allowed to fetch.
+ * Sharing one list would make the next infrastructure route silently
+ * uncrawlable, or a crawlable asset silently unprefixed.
+ */
+const INFRASTRUCTURE_DISALLOW: readonly string[] = [
+  '/api/',
+  '/__fc/',
+  '/__forge_beacon',
+  '/ping',
+];
+
+/**
+ * Without a public origin the storefront asserts nothing, so `robots.txt`
+ * refuses the whole tree. With one, it mirrors the noindex set — the page
+ * rules are DERIVED from `noindex.ts` rather than restated, because a
+ * `robots.txt` that disagrees with the pages' own `robots` metadata is the
+ * exact drift this module exists to prevent.
+ *
+ * The `Sitemap:` line rides the origin BRANCH, not merely the origin value: the
+ * URL it names has to be absolute, and the document it points at is empty
+ * without an origin. Announcing an empty sitemap is a claim about the catalog;
+ * announcing nothing is the absence of one, which is all a deployment that has
+ * not been told its own address is entitled to say.
+ */
+export default function robots(): MetadataRoute.Robots {
+  const publicOrigin = getPublicOrigin();
+  if (publicOrigin === null) {
+    return { rules: { userAgent: '*', disallow: '/' } };
+  }
+
+  return {
+    rules: {
+      userAgent: '*',
+      allow: '/',
+      disallow: [
+        ...NOINDEX_PATHS,
+        ...INFRASTRUCTURE_DISALLOW,
+        ...NOINDEX_QUERY_KEYS.map((key) => `/*?${key}=`),
+      ],
+    },
+    sitemap: `${publicOrigin}/sitemap.xml`,
+  };
+}