@forgecart/cli 2.202608300703.0 → 2.202609190800.0

package/templates/storefront/src/lib/content/render-fields.tsx

@@ -0,0 +1,256 @@
+import type { ReactNode } from 'react';
+
+import { getAssetAlt } from '../asset-alt';
+import type { PageEntry, PageFieldValue } from '../forgecart';
+
+/**
+ * The generic renderer for an ACF page record (#1934, epic launch#50).
+ *
+ * A page definition is whatever the merchant built in the dashboard, so this
+ * file cannot know the fields it will be handed — it renders by ACF field TYPE,
+ * driven by the `__typename` the shop API discriminates every value with. The
+ * layout is deliberately plain: this is the scaffold a merchant edits, and a
+ * template that guessed at a design would be undone before it shipped.
+ *
+ * Order and labels come from the DEFINITIONS, not the values: the shop API
+ * returns field definitions in the order the editor arranged them, while the
+ * value list is storage order and means nothing to a reader. A definition with
+ * no value (a display-only field — a divider, a chart) simply has nothing to
+ * match and renders nothing, which is why no field-category test appears here.
+ *
+ * Repeater rows render one level deep, and the bound is a real one rather than
+ * an oversight: the shop operation unrolls the group tree three levels
+ * (fragments cannot recurse), so each level is a DIFFERENT generated type and a
+ * general recursion has no single shape to stand on. One level covers the
+ * "sections of a page" shape this route exists for; deeper trees are a
+ * follow-up with the operation change they need.
+ */
+
+/** What this renderer needs of a field definition — nothing about its storage. */
+export interface RenderableDefinition {
+  readonly fieldName: string;
+  readonly title?: string | null;
+  readonly hideTitle?: boolean | null;
+  readonly children?: readonly RenderableDefinition[] | null;
+}
+
+/** One repeater as an entry carries it: a named group of rows. */
+type PageRepeater = PageEntry['groups'][number];
+
+export function PageFields({
+  definitions,
+  entry,
+}: {
+  definitions: readonly RenderableDefinition[];
+  entry: PageEntry;
+}): ReactNode {
+  return (
+    <div className="space-y-8">
+      {definitions.map((definition) => (
+        <PageField
+          key={definition.fieldName}
+          definition={definition}
+          value={entry.fields.find((field) => field.name === definition.fieldName)}
+          repeater={entry.groups.find((group) => group.name === definition.fieldName)}
+        />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * One definition's section — its label and whatever it holds.
+ *
+ * A field with neither a value nor rows renders NOTHING, not an empty section:
+ * an unpublished column reads as null (the shop API's live-column gating) and a
+ * merchant who left a field blank meant to leave it blank. Either way a bare
+ * heading over nothing is noise on a public page.
+ */
+function PageField({
+  definition,
+  value,
+  repeater,
+}: {
+  definition: RenderableDefinition;
+  value: PageFieldValue | undefined;
+  repeater: PageRepeater | undefined;
+}): ReactNode {
+  const body = repeater ? renderRepeater(repeater, definition.children ?? []) : renderValue(value);
+  if (body === null) return null;
+
+  return (
+    // `data-fc-field` carries the field's identity into the DOM: it is what a
+    // merchant styles a single field by, and the stable hook the storefront
+    // e2e reads.
+    <section className="space-y-2" data-fc-field={definition.fieldName}>
+      {definition.hideTitle !== true && definition.title ? (
+        <h2 className="text-xl font-semibold tracking-tight">{definition.title}</h2>
+      ) : null}
+      {body}
+    </section>
+  );
+}
+
+/** A repeater's rows, each row rendering its own members through the same law. */
+function renderRepeater(
+  repeater: PageRepeater,
+  members: readonly RenderableDefinition[],
+): ReactNode {
+  if (repeater.entries.length === 0) return null;
+  return (
+    <div className="space-y-6">
+      {repeater.entries.map((row) => (
+        <div key={row.id} className="space-y-2">
+          {members.map((member) => {
+            const body = renderValue(row.fields.find((field) => field.name === member.fieldName));
+            if (body === null) return null;
+            return (
+              <div key={member.fieldName} data-fc-field={member.fieldName}>
+                {member.hideTitle !== true && member.title ? (
+                  <h3 className="text-sm font-semibold text-base-content/70">{member.title}</h3>
+                ) : null}
+                {body}
+              </div>
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * One stored value as markup, or `null` when it holds nothing to show.
+ *
+ * An exhaustive `switch` over the discriminated union rather than a lookup
+ * table, and the `default` arm is the reason: it assigns the value to `never`,
+ * so adding an ACF field type without teaching this file about it is a COMPILE
+ * error in the merchant's scaffold instead of a section that silently renders
+ * blank on a live page.
+ */
+function renderValue(value: PageFieldValue | undefined): ReactNode {
+  if (value === undefined) return null;
+
+  switch (value.__typename) {
+    case 'AcfStringValue':
+      return text(value.stringValue);
+    case 'AcfIntValue':
+      return absent(value.intValue) ? null : text(String(value.intValue));
+    case 'AcfFloatValue':
+      return absent(value.floatValue) ? null : text(String(value.floatValue));
+    case 'AcfBoolValue':
+      return absent(value.boolValue) ? null : text(value.boolValue ? 'Yes' : 'No');
+    case 'AcfDateValue':
+      // The API serializes DateTime as ISO 8601; rendered as `<time>` with the
+      // machine-readable value intact, and NOT locale-formatted here — a
+      // formatted date is a merchant presentation choice, and guessing one in
+      // the scaffold would be a decision nobody made.
+      return absent(value.dateValue) ? null : (
+        <time dateTime={value.dateValue} className="text-base-content/80">
+          {value.dateValue}
+        </time>
+      );
+    case 'AcfStringListValue':
+      return list(value.stringListValue);
+    case 'AcfJsonValue':
+      // Shown verbatim in a code block: JSON on a page is structured data the
+      // merchant's own components consume, and pretty-printing it here would be
+      // this file inventing a shape for someone else's payload.
+      return absent(value.jsonValue) ? null : (
+        <pre className="overflow-x-auto rounded-box bg-base-200 p-4 text-xs">{value.jsonValue}</pre>
+      );
+    case 'AcfRichTextValue':
+      // The server-rendered projection, never the raw delta: `html` is produced
+      // by the API's own sanitizing renderer, which is the one place that
+      // decision belongs.
+      //
+      // The guard is also what satisfies the seam: `dangerouslySetInnerHTML`
+      // takes `string | TrustedHTML`, so the projection is rendered only once
+      // it IS a string — never coerced past an absence with a `?? ''`, which
+      // would publish an empty rich-text section as if the merchant had
+      // written one.
+      return absent(value.html) ? null : (
+        <div
+          className="max-w-none text-base leading-relaxed text-base-content/80"
+          dangerouslySetInnerHTML={{ __html: value.html }}
+        />
+      );
+    case 'AcfAssetValue':
+      return value.asset ? <AssetImage asset={value.asset} /> : null;
+    case 'AcfAssetListValue':
+      return value.assets.length === 0 ? null : (
+        <div className="grid grid-cols-2 gap-4 sm:grid-cols-3">
+          {value.assets.map((asset) => (
+            <AssetImage key={asset.id} asset={asset} />
+          ))}
+        </div>
+      );
+    case 'AcfRelationValue':
+      // The API resolves the related row's display summary; the id alone would
+      // be meaningless on a storefront, and a dangling reference resolves to
+      // no summary at all, which renders as nothing rather than as a raw uuid.
+      return value.entity ? text(value.entity.label) : null;
+    case 'AcfRelationListValue':
+      return list(value.entities.map((entity) => entity.label));
+    default:
+      return exhausted(value);
+  }
+}
+
+/** One asset as an image — decorative unless the merchant described it. */
+function AssetImage({ asset }: { asset: { preview: string; altText?: string | null } }): ReactNode {
+  return (
+    // eslint-disable-next-line @next/next/no-img-element
+    <img
+      src={asset.preview}
+      alt={getAssetAlt(asset)}
+      className="w-full rounded-box border border-base-300 object-cover"
+    />
+  );
+}
+
+function text(content: string | null | undefined): ReactNode {
+  if (absent(content) || content.trim() === '') return null;
+  return <p className="text-base leading-relaxed text-base-content/80">{content}</p>;
+}
+
+function list(items: readonly string[] | null | undefined): ReactNode {
+  if (absent(items) || items.length === 0) return null;
+  return (
+    <ul className="list-inside list-disc space-y-1 text-base-content/80">
+      {items.map((item, index) => (
+        <li key={`${item}-${String(index)}`}>{item}</li>
+      ))}
+    </ul>
+  );
+}
+
+/**
+ * Is there nothing here?
+ *
+ * The generated SDK marks every nullable selection OPTIONAL as well as
+ * nullable (`stringValue?: Maybe<string>`), so "the merchant left this empty"
+ * reaches this file as `null` from the API answering today and as `undefined`
+ * from any pod whose SDK does not carry the selection at all. Both mean the
+ * same thing to a reader, and collapsing them in ONE predicate is what keeps a
+ * `String(undefined)`, an empty `<time>` or a bare `No` off a live page — each
+ * of which a `=== null` check alone would have rendered.
+ */
+function absent<T>(value: T | null | undefined): value is null | undefined {
+  return value === null || value === undefined;
+}
+
+/**
+ * The compile-time exhaustiveness check for the switch above: the parameter is
+ * `never`, so a new ACF field type stops this file from building until it is
+ * handled.
+ *
+ * At RUNTIME it renders nothing rather than throwing, and the asymmetry is
+ * deliberate. The only way to reach it is a pod whose generated SDK is older
+ * than the API answering it, and in that state the honest behaviour is to show
+ * the fields this build understands — a throw would blank the merchant's whole
+ * live page over one unknown section.
+ */
+function exhausted(_value: never): null {
+  return null;
+}

package/templates/storefront/src/lib/content/resolve-page.ts

@@ -0,0 +1,143 @@
+import { isLocaleSegment } from '../locale/grammar';
+
+/**
+ * What a storefront page URL resolves to (#1934, epic launch#50) — the WHOLE
+ * decision behind `/pages/<route>`, as a value.
+ *
+ * PURE BY CONTRACT, for the reason `lib/seo/resolve-path.ts` is: this is the
+ * law that decides between a rendered page and a real 404, and
+ * `tool/storefront-template-spec` imports it directly by relative path from
+ * OUTSIDE the scaffold, so nothing reachable from here may need the template's
+ * Next toolchain. The route file is left as dispatch — it turns `notFound` into
+ * Next's `notFound()` and `ok` into markup, and decides nothing itself.
+ *
+ * The inputs are declared STRUCTURALLY rather than imported from the SDK for
+ * the same reason (`ResolvableProduct` precedent): the generated query types
+ * satisfy these shapes structurally, so the scaffold's own `tsc` proves the
+ * assignment while this module stays importable with no `paths`.
+ */
+
+/**
+ * The subset of a page definition this decision reads, declared AS THE SHOP
+ * API'S GENERATED TYPES CARRY IT.
+ *
+ * Every nullable selection reaches a scaffold OPTIONAL as well as nullable
+ * (`route?: Maybe<string>`), so a contract spelled `string | null` would refuse
+ * the very value the query produces — and, this module having no compiler of
+ * its own in this repository, the refusal would surface in the merchant's
+ * `next build` instead of here. Admitting the shape is therefore part of the
+ * contract, not a laxity: what each absence MEANS is decided in the table
+ * below, once, rather than guessed at by each caller.
+ */
+export interface RoutedPageGroup {
+  /**
+   * `'page'` for a storefront page; anything else — a data definition, or a
+   * selection from a pod whose SDK does not carry the field — is not one.
+   */
+  readonly kind?: string | null;
+  /**
+   * The route the definition is mounted at. Absent means mounted NOWHERE: the
+   * column is nullable because most definitions are data rather than pages.
+   */
+  readonly route?: string | null;
+}
+
+/**
+ * Why a page URL is a 404. Four distinct causes, kept apart because they answer
+ * different questions about a deployment — "the merchant has not published
+ * this yet" and "this URL was never a page" look identical to a visitor and are
+ * nothing alike to whoever is debugging.
+ */
+export type PageNotFoundReason =
+  /**
+   * The slug is a two-letter locale segment. No page may hold one (launch#54
+   * W1-7 — the server refuses to mint such a route rather than auto-suffixing
+   * it), so this URL can never carry content in any deployment. Judged first
+   * and without consulting the lookup, so the rule is stated where it is true
+   * rather than inferred from an empty result.
+   */
+  | 'reserved-locale-segment'
+  /**
+   * No page definition of this channel is mounted at this route: the lookup
+   * answered nothing, or what it answered carries no route of its own and is
+   * therefore mounted nowhere.
+   */
+  | 'unknown-route'
+  /** Something answered, but it is not a page definition. */
+  | 'not-a-page'
+  /**
+   * The page exists and has nothing a visitor may see: never given a record, or
+   * holding only records the publish fence hides — a DRAFT, or one SCHEDULED
+   * for a moment that has not arrived. The shop API already removed those rows
+   * (it fences every storefront read to published content), so this arm is the
+   * renderer HONOURING an empty result, never a second publish check.
+   */
+  | 'no-live-content';
+
+/**
+ * The answer for one page URL.
+ *
+ * The `ok` arm carries BOTH halves of what the route renders, narrowed to the
+ * caller's own types. That is why it is generic rather than a bare verdict: a
+ * caller that had to re-check `group !== null` after a resolution that already
+ * proved it would be asserting what the law just decided.
+ */
+export type PageResolution<TGroup, TEntry> =
+  | { kind: 'ok'; group: TGroup; entry: TEntry }
+  | { kind: 'notFound'; reason: PageNotFoundReason };
+
+export interface ResolvePageInput<TGroup, TEntry> {
+  /** The slug exactly as it appeared in the URL, locale prefix already stripped. */
+  requestedRoute: string;
+  /** What `pageByRoute` answered, or null when it answered nothing. */
+  group: TGroup | null;
+  /**
+   * The page's visible records, in the order the CALLER asked for. A page is
+   * one URL, so it serves one record: the first of these. Which record that is
+   * is the caller's decision and belongs at the query (see `getPageEntries`),
+   * not here.
+   */
+  entries: readonly TEntry[];
+}
+
+/**
+ * Decide the honest answer for a page URL.
+ *
+ * TOTAL over its input and ordered so each arm may assume the ones above it did
+ * not fire. Two of the four refusals are the feature's own contract — an
+ * unpublished or not-yet-live page answers 404 — and the other two are what
+ * make the function total.
+ */
+export function resolvePage<TGroup extends RoutedPageGroup, TEntry>({
+  requestedRoute,
+  group,
+  entries,
+}: ResolvePageInput<TGroup, TEntry>): PageResolution<TGroup, TEntry> {
+  if (isLocaleSegment(requestedRoute)) {
+    return { kind: 'notFound', reason: 'reserved-locale-segment' };
+  }
+
+  if (group === null) return { kind: 'notFound', reason: 'unknown-route' };
+
+  // A boundary check, not a redundant one: the shop query returns the general
+  // field-definition type and nothing in that TYPE says "page", so this is the
+  // template asserting that what it is about to render as a page is one — the
+  // same posture `parseScaffoldedRoute` takes toward a value another process
+  // wrote.
+  if (group.kind !== 'page') return { kind: 'notFound', reason: 'not-a-page' };
+
+  // Mounted-ness, read back off the answer itself, in the same posture as the
+  // kind check above: `pageByRoute` matched this group BY its route, so one
+  // that carries none contradicts the question it answered. Stating that as a
+  // 404 is what keeps the route from rendering a page no URL owns — and it is
+  // why the absence is resolved HERE rather than by a caller that would have
+  // to invent a meaning for it.
+  if (group.route === null || group.route === undefined) {
+    return { kind: 'notFound', reason: 'unknown-route' };
+  }
+
+  const entry = entries[0];
+  if (entry === undefined) return { kind: 'notFound', reason: 'no-live-content' };
+
+  return { kind: 'ok', group, entry };
+}

package/templates/storefront/src/lib/experiments.ts

@@ -10,6 +10,7 @@ import { after } from 'next/server';
 import { cache } from 'react';
 import { uuidv7 } from 'uuidv7';
 
+import { SESSION_COOKIE } from './session-cookies';
 import { forwardTrackEvent, getUpstreamConfig, isObviousBot } from './track-forward';
 import type { TrackEventInput, UpstreamConfig } from './track-forward';
 
@@ -61,7 +62,6 @@ import type { TrackEventInput, UpstreamConfig } from './track-forward';
  */
 
 const VISITOR_COOKIE = 'forgecart-visitor';
-const SESSION_COOKIE = 'forgecart-session';
 const FORCED_ENTRY_COOKIE = 'forgecart-exp-force';
 
 /** Delivery-config cache TTL — the design doc's 60s config-plane freshness. */