@forgecart/cli 2.202610052310.0 → 2.202610060357.0

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

@@ -0,0 +1,217 @@
+import type { Metadata } from 'next';
+import { connection } from 'next/server';
+import { Suspense } from 'react';
+import { cache } from 'react';
+
+import { LocaleLink } from '../components/LocaleLink';
+import { ProductCard } from '../components/ProductCard';
+import { buttonVariants } from '../components/ui/button';
+import { Skeleton } from '../components/ui/skeleton';
+import { cn } from '../components/ui/utils';
+import { getAssetAlt } from '../lib/asset-alt';
+import { getVariant } from '../lib/experiments';
+import { getFeaturedProducts } 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 data sections below are per-request holes streamed inside their Suspense
+// boundaries. The page itself is dynamic like every route (the root layout
+// reads the request locale — see next.config.js).
+
+/** One featured read per request, shared by both holes (React request cache). */
+const featured = cache(async () => getFeaturedProducts(4));
+
+/**
+ * The landing surface is indexable — unless the URL carries query state
+ * (an experiment pin, a preview) that makes it a VIEW of the page competing
+ * with the page's own address.
+ *
+ * `title: null` because the store's landing page has no name of its own: it IS
+ * the store, so it takes the shop name alone rather than composing something
+ * like `Home | Acme`. The description is the shell's, inherited by omission.
+ */
+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,
+    // The canonical is built from the BASE path, so `/?fc-exp=hero:b` declares
+    // `/` as its address — the query-state copy points at the page it is a view
+    // of, which is the whole reason those URLs are noindex rather than ignored.
+    pathname: '/',
+    pathsByLocale: staticPathsByLocale(languageCodes, '/'),
+    searchParams: resolvedSearchParams,
+    title: null,
+  });
+}
+
+/**
+ * Home — the store's landing surface (Blueprint `pages/product-landing-page`):
+ * a product-led hero with ONE dominant conversion action, an editorial
+ * featured grid (first product large — asymmetry, not a uniform tile wall),
+ * and a closing conversion band. Every color is a semantic token; the brand
+ * lives in the `:root` block of globals.css alone.
+ */
+export default async function HomePage() {
+  const { binding } = await getRequestLocale();
+  return (
+    <div className="space-y-16">
+      <Suspense fallback={<HeroSkeleton />}>
+        <Hero locale={binding} />
+      </Suspense>
+
+      <section aria-labelledby="featured-heading">
+        <div className="mb-6 flex items-baseline justify-between gap-4">
+          <h2 id="featured-heading" className="text-2xl font-semibold tracking-tight">
+            Featured
+          </h2>
+          <LocaleLink
+            href="/products"
+            locale={binding}
+            className="text-sm text-muted-foreground underline-offset-4 hover:text-foreground hover:underline"
+          >
+            View all products
+          </LocaleLink>
+        </div>
+        <Suspense fallback={<GridSkeleton />}>
+          <FeaturedGrid locale={binding} />
+        </Suspense>
+      </section>
+    </div>
+  );
+}
+
+/**
+ * The experiment-split hero (design doc F-B): variants are code branches
+ * keyed on `variantKey`. `hero-headline` is the template's reference
+ * experiment — create one with that key (variants `control` + `b`) in the
+ * dashboard and this hero starts splitting; until then `variantKey` is null
+ * and the default copy renders. `data-fc-variant` mirrors the assignment for
+ * debugging/verification; exposure tracking happens server-side.
+ */
+async function Hero({ locale }: { locale: LocaleBinding }) {
+  // Request-time hole: streamed inside its Suspense boundary.
+  await connection();
+  const [products, hero] = await Promise.all([featured(), getVariant('hero-headline')]);
+  const heroProduct = products.find((product) => product.featuredAsset) ?? null;
+
+  return (
+    <section
+      data-fc-variant={hero.variantKey ?? 'default'}
+      className="overflow-hidden rounded-xl border bg-card text-card-foreground shadow-sm"
+    >
+      <div className="flex w-full flex-col gap-10 p-8 lg:flex-row lg:items-center lg:p-12">
+        <div className="max-w-xl lg:flex-1">
+          <h1 className="text-4xl font-bold tracking-tight text-balance sm:text-5xl">
+            Welcome to the shop
+          </h1>
+          <p className="mt-4 text-muted-foreground text-pretty">
+            {hero.variantKey === 'b'
+              ? 'Fresh picks, fair prices — see what everyone is adding to their carts.'
+              : 'This storefront is served by a ForgeCart channel. Browse the catalog and add products to your cart.'}
+          </p>
+          <div className="mt-8">
+            <LocaleLink href="/products" locale={locale} className={buttonVariants({ size: 'lg' })}>
+              Shop all products
+            </LocaleLink>
+          </div>
+        </div>
+        {heroProduct?.featuredAsset && (
+          <LocaleLink
+            href={`/products/${heroProduct.slug}`}
+            locale={locale}
+            className="w-full max-w-md lg:flex-1"
+            aria-label={`View ${heroProduct.name}`}
+          >
+            <figure className="aspect-square overflow-hidden rounded-lg bg-muted">
+              {/* Plain <img> keeps the template dependency-free of next/image config. */}
+              {/* eslint-disable-next-line @next/next/no-img-element */}
+              <img
+                src={heroProduct.featuredAsset.preview}
+                alt={getAssetAlt(heroProduct.featuredAsset)}
+                className="h-full w-full object-cover"
+              />
+            </figure>
+          </LocaleLink>
+        )}
+      </div>
+    </section>
+  );
+}
+
+async function FeaturedGrid({ locale }: { locale: LocaleBinding }) {
+  await connection();
+  const products = await featured();
+
+  if (products.length === 0) {
+    return (
+      <p className="text-muted-foreground">
+        No products yet — add your first product in the dashboard and it appears here.
+      </p>
+    );
+  }
+
+  return (
+    <>
+      <div className="grid grid-cols-2 gap-4 sm:gap-6 lg:grid-cols-4">
+        {products.map((product, index) => (
+          <div key={product.id} className={index === 0 ? 'col-span-2 row-span-2' : undefined}>
+            <ProductCard product={product} locale={locale} emphasis={index === 0} />
+          </div>
+        ))}
+      </div>
+
+      <section className="mt-16 rounded-xl bg-muted">
+        <div className="flex flex-col items-center gap-6 px-6 py-14 text-center">
+          <h2 className="text-3xl font-bold tracking-tight text-balance">
+            Find something you like?
+          </h2>
+          <p className="max-w-md text-muted-foreground text-pretty">
+            The whole catalog ships from this store — browse everything in one place.
+          </p>
+          <LocaleLink href="/products" locale={locale} className={cn(buttonVariants(), 'w-64')}>
+            Browse the catalog
+          </LocaleLink>
+        </div>
+      </section>
+    </>
+  );
+}
+
+function HeroSkeleton() {
+  return (
+    <div className="rounded-xl border bg-card shadow-sm" aria-busy="true">
+      <div className="flex w-full flex-col gap-10 p-8 lg:flex-row lg:p-12">
+        <div className="w-full max-w-xl space-y-4 lg:flex-1">
+          <Skeleton className="h-12 w-3/4" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-2/3" />
+          <Skeleton className="mt-4 h-12 w-48" />
+        </div>
+        <Skeleton className="aspect-square w-full max-w-md lg:flex-1" />
+      </div>
+    </div>
+  );
+}
+
+function GridSkeleton() {
+  return (
+    <div className="grid grid-cols-2 gap-4 sm:gap-6 lg:grid-cols-4" aria-busy="true">
+      <div className="col-span-2 row-span-2">
+        <Skeleton className="h-full min-h-72 w-full" />
+      </div>
+      <Skeleton className="aspect-square w-full" />
+      <Skeleton className="aspect-square w-full" />
+      <Skeleton className="aspect-square w-full" />
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/app/pages/[slug]/not-found.tsx

@@ -0,0 +1,24 @@
+import { LocaleLink } from '../../../components/LocaleLink';
+import { buttonVariants } from '../../../components/ui/button';
+import { getRequestLocale } from '../../../lib/locale/request-binding';
+
+/**
+ * What a visitor sees at a page URL that holds nothing: an unknown route, or a
+ * page whose content is not published (or not published YET). The copy does not
+ * distinguish them on purpose — "this is scheduled for Tuesday" is the
+ * merchant's information, not the public's.
+ */
+export default async function AcfPageNotFound() {
+  const { binding } = await getRequestLocale();
+  return (
+    <div className="space-y-4">
+      <h1 className="text-2xl font-bold tracking-tight text-foreground">Page not found</h1>
+      <p className="text-muted-foreground">
+        We couldn&apos;t find that page. It may have been moved or taken down.
+      </p>
+      <LocaleLink href="/" locale={binding} className={buttonVariants()}>
+        Back to the shop
+      </LocaleLink>
+    </div>
+  );
+}

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

@@ -0,0 +1,115 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { cache } from 'react';
+
+import { pageContentClaims } from '../../../lib/content/page-metadata';
+import { PageFields } from '../../../lib/content/render-fields';
+import { resolvePage } from '../../../lib/content/resolve-page';
+import {
+  getPageByRoute,
+  getPageEntries,
+  type PageEntry,
+  type PageGroup,
+} from '../../../lib/forgecart';
+import { getRequestLocale } from '../../../lib/locale/request-binding';
+import { routeMetadata } from '../../../lib/seo/metadata';
+import type { RouteSearchParams } from '../../../lib/seo/noindex';
+import { PAGE_ROUTE_PREFIX } from '../../../lib/seo/sitemap-entries';
+
+/**
+ * The merchant's own pages (#1934, epic launch#50), served at the route the
+ * shop API minted for the page definition.
+ *
+ * Locale-prefixed addresses land here too and cost nothing: the route tree is
+ * FLAT by law (#1041) and the middleware rewrites `/de/pages/x` onto this same
+ * file with the locale carried on a request header, so `/pages/x` and every
+ * `/<xx>/pages/x` are one route with one decision.
+ *
+ * FORCE-DYNAMIC, explicitly. "An unpublished page answers 404 on the NEXT
+ * request" is this feature's contract, and a contract must not rest on the
+ * incidental fact that some module downstream happens to read `headers()`. No
+ * `revalidate`, no `use cache`: a window here would serve a page the merchant
+ * has already taken down, which is the one failure this route may not have.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * The page's definition AND its visible record, read once per request.
+ *
+ * Both halves together, because the 404 decision needs both and Next invokes
+ * `generateMetadata` and the page as separate calls — without React's request
+ * cache the two would resolve independently, and a page unpublished between
+ * them would emit indexable metadata for a URL that then 404s.
+ *
+ * The entries read is skipped when nothing is mounted at the route: there is no
+ * definition code to ask about, and the resolution's answer is already settled.
+ */
+const pageForRequest = cache(
+  async (route: string): Promise<{ group: PageGroup | null; entries: PageEntry[] }> => {
+    const group = await getPageByRoute(route);
+    if (group === null) return { group: null, entries: [] };
+    return { group, entries: await getPageEntries(group.code) };
+  },
+);
+
+/**
+ * A page's metadata comes from the same resolution the route acts on, so the
+ * head and the status can never disagree about what this URL is.
+ *
+ * Its CONTENT claims — title, description, social card, alternates and
+ * indexability — are the record's per-language SEO sidecar (#1375), decided in
+ * `lib/content/page-metadata.ts` by the rules the product route uses: the
+ * definition's `seoSources` mapping and the merchant's stored overrides arrive
+ * already resolved into each language, and a language with no copy of its own
+ * renders as a fallback that claims nothing (noindex, no canonical, never an
+ * hreflang alternate). This file only dispatches.
+ */
+export async function generateMetadata({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<RouteSearchParams>;
+}): Promise<Metadata> {
+  const [{ slug }, resolvedSearchParams, { binding, languageCodes, shopName, channelResolved }] =
+    await Promise.all([params, searchParams, getRequestLocale()]);
+  const { group, entries } = await pageForRequest(slug);
+  const resolution = resolvePage({ requestedRoute: slug, group, entries });
+  const pathname = `${PAGE_ROUTE_PREFIX}/${slug}`;
+
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname,
+    searchParams: resolvedSearchParams,
+    ...pageContentClaims(resolution, { locale: binding.locale, languageCodes, pathname }),
+  });
+}
+
+/**
+ * The resolution runs in the page SHELL, above any boundary, and that placement
+ * is the whole correctness of this route's status codes: `notFound()` can only
+ * set a status where Next assigns one, and raised from inside a Suspense
+ * boundary the shell has already flushed a 200 — a crawler then INDEXES the
+ * not-found page instead of dropping it (the same law `products/[slug]`
+ * carries, measured there).
+ *
+ * There is no boundary at all here, and that follows from the same fact: the
+ * two reads ARE this page, so streaming a skeleton would buy nothing while the
+ * only content loaded.
+ */
+export default async function AcfPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const { group, entries } = await pageForRequest(slug);
+  const resolution = resolvePage({ requestedRoute: slug, group, entries });
+
+  if (resolution.kind === 'notFound') notFound();
+
+  return (
+    <article className="space-y-8">
+      <h1 className="text-3xl font-bold tracking-tight text-balance">{resolution.group.name}</h1>
+      <PageFields definitions={resolution.group.fieldDefinitions} entry={resolution.entry} />
+    </article>
+  );
+}

package/templates/storefront-shadcn/src/app/ping/route.ts

@@ -0,0 +1,21 @@
+/**
+ * Liveness ping for the in-pod dev-server readiness probe.
+ *
+ * Returns a static 200 with no layout, data fetch, or session. The workspace's
+ * readiness probe hits THIS route (not `/`) on a fast cadence while the store is
+ * STARTING and then a slow liveness cadence forever — and `/` renders the
+ * cart-aware layout, whose `activeOrder` call MATERIALISES an active order on every
+ * request. Probing `/` therefore minted a throwaway order on every poll; probing a
+ * route handler renders nothing and touches no session, so readiness polling stays
+ * side-effect-free.
+ *
+ * Request access keeps it out of any static prerender so a production build serves
+ * it on demand exactly like `next dev` does — the probe always gets a fresh 200.
+ */
+
+export function GET(): Response {
+  return new Response('ok', {
+    status: 200,
+    headers: { 'content-type': 'text/plain' },
+  });
+}

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

@@ -0,0 +1,18 @@
+import { LocaleLink } from '../../../components/LocaleLink';
+import { buttonVariants } from '../../../components/ui/button';
+import { getRequestLocale } from '../../../lib/locale/request-binding';
+
+export default async function ProductNotFound() {
+  const { binding } = await getRequestLocale();
+  return (
+    <div className="space-y-4">
+      <h1 className="text-2xl font-bold tracking-tight text-foreground">Product not found</h1>
+      <p className="text-muted-foreground">
+        We couldn&apos;t find that product. It may have been removed.
+      </p>
+      <LocaleLink href="/products" locale={binding} className={buttonVariants()}>
+        Back to products
+      </LocaleLink>
+    </div>
+  );
+}