@tokenoftrust/storefront-runner 2.4.72 → 2.4.73

package/apps/storefront/src/lib/chrome/model.ts

@@ -48,6 +48,11 @@ export {
   type ChromeHeader,
   type ChromeFooter,
   type ChromeConfig,
+  type ProductDetailsConfig,
+  type ProductDetailSpecRow,
+  type ProductAttributeLine,
+  type ProductMetafieldRef,
+  type ProductDetailFaqConfig,
   type ChromeAssignmentEntry,
   type ChromeAssignments,
   type ChromeAssignmentsValidationResult,

package/apps/storefront/src/pages/products/[handle].astro

@@ -29,6 +29,7 @@ import {
   resolveMembershipRule,
   DEFAULT_STACKING_POLICY,
   readReviewAggregate,
+  resolveProductDetails,
 } from "@tot/public-runtime";
 import type {
   ProductPurchaseOption,
@@ -110,7 +111,7 @@ function titleCase(s: string) {
   return s.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
-// Metafield reader.
+// Metafield reader (ToT-internal namespaces only — compliance.* below).
 const mf = (ns: string, key: string) =>
   product.metafields.find((m) => m.namespace === ns && m.key === key)?.value;
 
@@ -120,9 +121,16 @@ const mf = (ns: string, key: string) =>
 // unless BOTH numbers are real positives — so no fabricated rating can render.
 const { average: reviewAvg, count: reviewCount } = readReviewAggregate(product);
 
+// Declared PDP metafield->section mapping (ChromeConfig.productDetails,
+// content/chrome.json). No metafield namespace/key convention is assumed by
+// this template — a tenant's own catalog shape is declared, not guessed, so
+// behavior never branches on which tenant is rendering.
+const chrome = await Astro.locals.content.getChrome();
+const details = resolveProductDetails(product.metafields, chrome.productDetails);
+
 // Short description (merchant's concise summary) shown high on the PDP, like the
 // source store. The longer description_html still renders below the buy column.
-const shortDescription = mf("my_fields", "short_description") ?? mf("specs", "short_description");
+const shortDescription = details.shortDescription;
 
 // OG image = the real product image (Shopify CDN supports ?width=), sized for
 // social. Falls back to the tenant brand OG only when there's no usable image.
@@ -133,14 +141,14 @@ const ogImage =
     : undefined;
 
 // Product attributes shown the way the SOURCE STORE presents them: plain
-// "Label: value" lines below the description (Flavors / VG % / Bottle Type),
-// sourced from F:-prefixed tags + merchant my_fields. The compliance.* metafields
-// are ToT-internal sync data and are NOT displayed — the source store doesn't
-// show them either (they gate shipping/eligibility, not merchandising).
+// "Label: value" lines below the description, sourced from F:-prefixed tags
+// (flavor) + the tenant's declared attributeLines (e.g. VG % / Bottle Type).
+// The compliance.* metafields are ToT-internal sync data and are NOT
+// displayed — the source store doesn't show them either (they gate
+// shipping/eligibility, not merchandising).
 // Each flavor links to that flavor filtered within the product's collection —
 // mirrors the source store's /collections/<handle>/<tag> pattern using our
-// existing ?tag= PLP filter. General: any tag → a filtered listing; only the
-// "F: " flavor-tag convention is merchant-specific (same as the display above).
+// existing ?tag= PLP filter.
 const flavorCollection = product.collections[0];
 const flavorTags = (product.tags ?? [])
   .filter((t) => t.startsWith("F: "))
@@ -151,8 +159,7 @@ const flavorTags = (product.tags ?? [])
       : undefined,
   }))
   .filter((f) => f.label);
-const vgPercentage = mf("my_fields", "vg_percentage");
-const bottleType = mf("my_fields", "bottle_type");
+const attributeLines = details.attributeLines;
 
 // State sales restrictions (ToT compliance sync). Where this can't ship/sell.
 let restrictedStates: string[] = [];
@@ -169,7 +176,6 @@ if (restrictedRaw) {
 // Legal/safety disclaimer (scraped from the store's own PDP by the migration),
 // per product category — sub-ohm on salts, battery on devices, etc. Selected by
 // product_type (or the compliance.product_category metafield); default fallback.
-const chrome = await Astro.locals.content.getChrome();
 const productCategory = product.product_type || mf("compliance", "product_category");
 const disclaimer =
   (productCategory && chrome.disclaimers?.[productCategory]) || chrome.disclaimer;
@@ -440,7 +446,7 @@ const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
           the longer description, then plain "Label: value" lines (no spec table). */}
       <div class="mt-9 border-t border-[var(--color-border)] pt-7">
         <div class="rte text-[var(--color-text)]" set:html={product.description_html} />
-        {(flavorTags.length > 0 || vgPercentage || bottleType) && (
+        {(flavorTags.length > 0 || attributeLines.length > 0) && (
           <div class="mt-5 space-y-1.5 text-sm leading-relaxed">
             {flavorTags.length > 0 && (
               <p>
@@ -457,12 +463,9 @@ const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
                 ))}
               </p>
             )}
-            {vgPercentage && (
-              <p><span class="text-[var(--color-muted)]">VG Percentage:</span> {vgPercentage}</p>
-            )}
-            {bottleType && (
-              <p><span class="text-[var(--color-muted)]">Bottle Type:</span> {bottleType}</p>
-            )}
+            {attributeLines.map((line) => (
+              <p><span class="text-[var(--color-muted)]">{line.label}:</span> {line.value}</p>
+            ))}
           </div>
         )}
       </div>
@@ -506,6 +509,70 @@ const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
     </div>
   </div>
 
+  {/* Declared PDP sections (spec rows, ingredients, FAQ, box contents, age
+      notice) — every row/section comes from the tenant's own
+      ChromeConfig.productDetails mapping (content/chrome.json), read above
+      into `details`. A section is simply absent when its declared metafield
+      has no value on this product — never an empty label. */}
+  {details.specRows.length > 0 && (
+    <Section title={details.specHeading} widget="product-details">
+      <dl class="grid grid-cols-1 gap-x-8 gap-y-4 sm:grid-cols-2 lg:grid-cols-3">
+        {details.specRows.map((row) => (
+          <div class="border-b border-[var(--color-border)] pb-3">
+            <dt class="text-xs font-medium uppercase tracking-wide text-[var(--color-muted)]">{row.label}</dt>
+            <dd class="mt-1 text-sm font-medium text-[var(--color-text)]">{row.value}</dd>
+          </div>
+        ))}
+      </dl>
+    </Section>
+  )}
+
+  {details.boxContents && (
+    <div class="container-prose">
+      <p class="text-sm leading-relaxed">
+        <span class="text-[var(--color-muted)]">{details.boxContents.label}:</span> {details.boxContents.value}
+      </p>
+    </div>
+  )}
+
+  {details.ingredients && (
+    <Section title={details.ingredients.heading} widget="product-ingredients" tone="surface">
+      <p class="text-sm leading-relaxed text-[var(--color-text)]">{details.ingredients.text}</p>
+      {details.factCheckedBy && (
+        <p class="mt-3 text-xs text-[var(--color-muted)]">{details.factCheckedBy}</p>
+      )}
+    </Section>
+  )}
+
+  {details.ageNotice && (
+    <div class="container-prose">
+      <aside
+        role="note"
+        class="rounded-[var(--radius-md)] border border-[var(--color-border)] bg-[var(--color-surface)] px-5 py-4"
+      >
+        <strong class="block text-sm font-display font-semibold text-[var(--color-text)]">
+          {details.ageNotice.title}
+        </strong>
+        <p class="mt-1 text-sm text-[var(--color-muted)]">{details.ageNotice.text}</p>
+      </aside>
+    </div>
+  )}
+
+  {details.faq && (
+    <Section title={details.faq.heading} widget="product-faq">
+      <div class="divide-y divide-[var(--color-border)]">
+        {details.faq.items.map((item) => (
+          <details class="group py-4">
+            <summary class="cursor-pointer list-none font-display text-sm font-medium text-[var(--color-text)]">
+              {item.question}
+            </summary>
+            <p class="mt-2 text-sm leading-relaxed text-[var(--color-muted)]">{item.answer}</p>
+          </details>
+        ))}
+      </div>
+    </Section>
+  )}
+
   {/* Customer reviews — real content migrated from the store's reviews app. */}
   {reviews.length > 0 && (
     <Section

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.72",
+  "version": "2.4.73",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/chrome.ts

@@ -407,6 +407,89 @@ export interface ChromeConfig {
    * compliance.product_category) — the source store renders a different legal
    * block per type (sub-ohm on salts, battery on devices). */
   disclaimers?: Record<string, string>;
+  /**
+   * Declared PDP metafield->section mapping (see {@link ProductDetailsConfig}).
+   * Replaces any hardcoded metafield-namespace convention in the renderer: a
+   * tenant whose catalog carries spec/FAQ/ingredient data under its own
+   * namespace declares the mapping here, and the PDP renders it — never a
+   * namespace the template assumes by tenant id.
+   */
+  productDetails?: ProductDetailsConfig;
+}
+
+/** One "Product Details" spec-table row, sourced from one declared metafield. */
+export interface ProductDetailSpecRow {
+  /** Metafield namespace, e.g. "custom". */
+  namespace: string;
+  /** Metafield key, e.g. "dv_puff_count". */
+  key: string;
+  /** Row label, e.g. "Puff Count". */
+  label: string;
+}
+
+/** One declared "Label: value" prose line below the description. */
+export interface ProductAttributeLine {
+  namespace: string;
+  key: string;
+  label: string;
+}
+
+/** A metafield reference (namespace + key), no label — used where the section
+ * itself supplies the heading/copy. */
+export interface ProductMetafieldRef {
+  namespace: string;
+  key: string;
+}
+
+/**
+ * FAQ entries stored as a fixed-width set of numbered metafields
+ * (`faq_q1`/`faq_a1` .. `faq_qN`/`faq_aN`) — the convention a source store's
+ * migrated FAQ block commonly uses. `{n}` in each pattern is replaced with
+ * 1..maxItems; a product missing a given pair simply has no entry for that n.
+ */
+export interface ProductDetailFaqConfig {
+  namespace: string;
+  /** Question key template containing a literal `{n}`, e.g. "faq_q{n}". */
+  questionKeyPattern: string;
+  /** Answer key template containing a literal `{n}`, e.g. "faq_a{n}". */
+  answerKeyPattern: string;
+  /** Highest n to probe (1-based). */
+  maxItems: number;
+  /** Section heading. Defaults to "Frequently Asked Questions". */
+  heading?: string;
+}
+
+/**
+ * Declared mapping from a tenant's own catalog metafield namespace/keys to PDP
+ * sections. Every section is OMITTED when its declared metafield has no value
+ * on a given product — never rendered with an empty label. Undeclared
+ * metafields are never read: only what's listed here reaches the page.
+ */
+export interface ProductDetailsConfig {
+  /** Ordered fallback list for the short summary shown near the buy button
+   * (first metafield with a value wins). */
+  shortDescription?: ProductMetafieldRef[];
+  /** Ordered "Label: value" prose lines below the long description. */
+  attributeLines?: ProductAttributeLine[];
+  /** "Product Details" spec-table/grid rows, in declared order. */
+  specRows?: ProductDetailSpecRow[];
+  /** Heading for the spec-row section. Defaults to "Product Details". */
+  specHeading?: string;
+  /** The ingredients paragraph metafield. */
+  ingredients?: ProductMetafieldRef & { heading?: string };
+  /** Byline under the ingredients text, e.g. "Fact Checked By: Staff". Static
+   * copy (not a metafield); shown only when `ingredients` resolves to a value. */
+  factCheckedBy?: string;
+  /**
+   * Age/compliance notice (e.g. "Adult Use Only (21+)"), rendered only when
+   * its declared metafield has a value. Copy is declared here, never a fixed
+   * string in the template, so it's accurate for any tenant/jurisdiction.
+   */
+  ageNotice?: ProductMetafieldRef & { title: string; text: string };
+  /** FAQ block sourced from numbered metafields. */
+  faq?: ProductDetailFaqConfig;
+  /** Box/package-contents line. */
+  boxContents?: ProductMetafieldRef & { label?: string };
 }
 
 // ---------------------------------------------------------------------------
@@ -726,6 +809,80 @@ function validateFooter(v: unknown, path: string, errors: string[]): v is Chrome
   return errors.length === before;
 }
 
+function validateMetafieldRef(v: unknown, path: string, errors: string[]): void {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return;
+  }
+  if (!isNonEmptyString(v.namespace)) errors.push(`${path}.namespace: required, non-empty string`);
+  if (!isNonEmptyString(v.key)) errors.push(`${path}.key: required, non-empty string`);
+}
+
+function validateProductDetails(v: unknown, path: string, errors: string[]): void {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return;
+  }
+  if (v.shortDescription !== undefined) {
+    if (!Array.isArray(v.shortDescription)) errors.push(`${path}.shortDescription: must be an array`);
+    else v.shortDescription.forEach((r, i) => validateMetafieldRef(r, `${path}.shortDescription[${i}]`, errors));
+  }
+  if (v.attributeLines !== undefined) {
+    if (!Array.isArray(v.attributeLines)) errors.push(`${path}.attributeLines: must be an array`);
+    else
+      v.attributeLines.forEach((r, i) => {
+        validateMetafieldRef(r, `${path}.attributeLines[${i}]`, errors);
+        if (isObject(r) && !isNonEmptyString(r.label)) {
+          errors.push(`${path}.attributeLines[${i}].label: required, non-empty string`);
+        }
+      });
+  }
+  if (v.specRows !== undefined) {
+    if (!Array.isArray(v.specRows)) errors.push(`${path}.specRows: must be an array`);
+    else
+      v.specRows.forEach((r, i) => {
+        validateMetafieldRef(r, `${path}.specRows[${i}]`, errors);
+        if (isObject(r) && !isNonEmptyString(r.label)) {
+          errors.push(`${path}.specRows[${i}].label: required, non-empty string`);
+        }
+      });
+  }
+  checkOptionalString(v.specHeading, `${path}.specHeading`, errors);
+  if (v.ingredients !== undefined) {
+    validateMetafieldRef(v.ingredients, `${path}.ingredients`, errors);
+    if (isObject(v.ingredients)) checkOptionalString(v.ingredients.heading, `${path}.ingredients.heading`, errors);
+  }
+  checkOptionalString(v.factCheckedBy, `${path}.factCheckedBy`, errors);
+  if (v.ageNotice !== undefined) {
+    validateMetafieldRef(v.ageNotice, `${path}.ageNotice`, errors);
+    if (isObject(v.ageNotice)) {
+      if (!isNonEmptyString(v.ageNotice.title)) errors.push(`${path}.ageNotice.title: required, non-empty string`);
+      if (!isNonEmptyString(v.ageNotice.text)) errors.push(`${path}.ageNotice.text: required, non-empty string`);
+    }
+  }
+  if (v.faq !== undefined) {
+    if (!isObject(v.faq)) {
+      errors.push(`${path}.faq: must be an object`);
+    } else {
+      if (!isNonEmptyString(v.faq.namespace)) errors.push(`${path}.faq.namespace: required, non-empty string`);
+      if (!isNonEmptyString(v.faq.questionKeyPattern) || !v.faq.questionKeyPattern.includes("{n}")) {
+        errors.push(`${path}.faq.questionKeyPattern: required string containing "{n}"`);
+      }
+      if (!isNonEmptyString(v.faq.answerKeyPattern) || !v.faq.answerKeyPattern.includes("{n}")) {
+        errors.push(`${path}.faq.answerKeyPattern: required string containing "{n}"`);
+      }
+      if (typeof v.faq.maxItems !== "number" || !Number.isInteger(v.faq.maxItems) || v.faq.maxItems < 1) {
+        errors.push(`${path}.faq.maxItems: required positive integer`);
+      }
+      checkOptionalString(v.faq.heading, `${path}.faq.heading`, errors);
+    }
+  }
+  if (v.boxContents !== undefined) {
+    validateMetafieldRef(v.boxContents, `${path}.boxContents`, errors);
+    if (isObject(v.boxContents)) checkOptionalString(v.boxContents.label, `${path}.boxContents.label`, errors);
+  }
+}
+
 /**
  * Validate `raw` (parsed JSON) as a `ChromeConfig`. Collects every violation
  * (not just the first) so a caller gets one actionable report. Trusts the
@@ -754,6 +911,7 @@ export function validateChromeConfig(raw: unknown): ChromeConfigValidationResult
     if (!isObject(raw.breadcrumbs)) errors.push("breadcrumbs: must be an object");
     else checkOptionalString(raw.breadcrumbs.homeLabel, "breadcrumbs.homeLabel", errors);
   }
+  if (raw.productDetails !== undefined) validateProductDetails(raw.productDetails, "productDetails", errors);
 
   if (errors.length > 0) return { ok: false, config: null, errors };
   return { ok: true, config: raw as unknown as ChromeConfig, errors: [] };

package/packages/public-runtime/src/index.ts

@@ -50,6 +50,7 @@ export * from "./customization-versioning.js";
 export * from "./customization-scripts.js";
 export * from "./customization-reconcile.js";
 export * from "./chrome.js";
+export * from "./product-details.js";
 // Declarative interaction tracking: the data-tot-el / -action / -placement
 // attribute contract, its single emit path, and the ONE delegated click
 // listener both document mounts install. Reads declared attributes only —

package/packages/public-runtime/src/product-details.ts

@@ -0,0 +1,160 @@
+/**
+ * Resolves a product's declared PDP sections (spec rows, ingredients, FAQ, box
+ * contents, age notice, short description, attribute lines) from its raw
+ * metafields plus the tenant's declared `ChromeConfig.productDetails` mapping.
+ *
+ * Pure and dependency-free: no namespace/key convention is read unless the
+ * tenant's own `productDetails` config names it, and a section whose declared
+ * metafield has no value on a given product is OMITTED entirely — never
+ * rendered with an empty label. This is what replaces a renderer hardcoding
+ * one merchant's metafield-namespace convention (e.g. "my_fields").
+ */
+import type {
+  ProductDetailsConfig,
+  ProductDetailSpecRow,
+  ProductAttributeLine,
+} from "./chrome.js";
+import type { Metafield } from "./product.js";
+
+export interface ResolvedSpecRow {
+  label: string;
+  value: string;
+}
+
+export interface ResolvedAttributeLine {
+  label: string;
+  value: string;
+}
+
+export interface ResolvedFaqItem {
+  question: string;
+  answer: string;
+}
+
+export interface ResolvedProductDetails {
+  shortDescription?: string;
+  attributeLines: ResolvedAttributeLine[];
+  specHeading: string;
+  specRows: ResolvedSpecRow[];
+  ingredients?: { heading: string; text: string };
+  factCheckedBy?: string;
+  ageNotice?: { title: string; text: string };
+  faq?: { heading: string; items: ResolvedFaqItem[] };
+  boxContents?: { label: string; value: string };
+}
+
+const DEFAULT_SPEC_HEADING = "Product Details";
+const DEFAULT_FAQ_HEADING = "Frequently Asked Questions";
+const DEFAULT_BOX_CONTENTS_LABEL = "What's in the box";
+
+function metafieldLookup(metafields: readonly Metafield[]): (namespace: string, key: string) => string | undefined {
+  const map = new Map<string, string>();
+  for (const m of metafields) {
+    const v = m.value?.trim();
+    if (v) map.set(`${m.namespace}.${m.key}`, v);
+  }
+  return (namespace, key) => map.get(`${namespace}.${key}`);
+}
+
+/**
+ * Resolve a product's declared sections. `config` undefined/empty => every
+ * section is absent (no fallback to any hardcoded namespace).
+ */
+export function resolveProductDetails(
+  metafields: readonly Metafield[] | undefined,
+  config: ProductDetailsConfig | undefined,
+): ResolvedProductDetails {
+  const mf = metafieldLookup(metafields ?? []);
+  const out: ResolvedProductDetails = {
+    attributeLines: [],
+    specHeading: config?.specHeading?.trim() || DEFAULT_SPEC_HEADING,
+    specRows: [],
+  };
+  if (!config) return out;
+
+  if (config.shortDescription) {
+    for (const ref of config.shortDescription) {
+      const value = mf(ref.namespace, ref.key);
+      if (value) {
+        out.shortDescription = value;
+        break;
+      }
+    }
+  }
+
+  if (config.attributeLines) {
+    out.attributeLines = resolveAttributeLines(config.attributeLines, mf);
+  }
+
+  if (config.specRows) {
+    out.specRows = resolveSpecRows(config.specRows, mf);
+  }
+
+  if (config.ingredients) {
+    const value = mf(config.ingredients.namespace, config.ingredients.key);
+    if (value) {
+      out.ingredients = { heading: config.ingredients.heading?.trim() || "Ingredients", text: value };
+      if (config.factCheckedBy?.trim()) out.factCheckedBy = config.factCheckedBy.trim();
+    }
+  }
+
+  if (config.ageNotice) {
+    const value = mf(config.ageNotice.namespace, config.ageNotice.key);
+    if (value) out.ageNotice = { title: config.ageNotice.title, text: config.ageNotice.text };
+  }
+
+  if (config.faq) {
+    const items = resolveFaq(config.faq, mf);
+    if (items.length > 0) {
+      out.faq = { heading: config.faq.heading?.trim() || DEFAULT_FAQ_HEADING, items };
+    }
+  }
+
+  if (config.boxContents) {
+    const value = mf(config.boxContents.namespace, config.boxContents.key);
+    if (value) {
+      out.boxContents = { label: config.boxContents.label?.trim() || DEFAULT_BOX_CONTENTS_LABEL, value };
+    }
+  }
+
+  return out;
+}
+
+function resolveAttributeLines(
+  lines: readonly ProductAttributeLine[],
+  mf: (namespace: string, key: string) => string | undefined,
+): ResolvedAttributeLine[] {
+  const out: ResolvedAttributeLine[] = [];
+  for (const line of lines) {
+    const value = mf(line.namespace, line.key);
+    if (value) out.push({ label: line.label, value });
+  }
+  return out;
+}
+
+function resolveSpecRows(
+  rows: readonly ProductDetailSpecRow[],
+  mf: (namespace: string, key: string) => string | undefined,
+): ResolvedSpecRow[] {
+  const out: ResolvedSpecRow[] = [];
+  for (const row of rows) {
+    const value = mf(row.namespace, row.key);
+    if (value) out.push({ label: row.label, value });
+  }
+  return out;
+}
+
+function resolveFaq(
+  faq: NonNullable<ProductDetailsConfig["faq"]>,
+  mf: (namespace: string, key: string) => string | undefined,
+): ResolvedFaqItem[] {
+  const items: ResolvedFaqItem[] = [];
+  for (let n = 1; n <= faq.maxItems; n++) {
+    const qKey = faq.questionKeyPattern.replace("{n}", String(n));
+    const aKey = faq.answerKeyPattern.replace("{n}", String(n));
+    const question = mf(faq.namespace, qKey);
+    const answer = mf(faq.namespace, aKey);
+    if (question && answer) items.push({ question, answer });
+  }
+  return items;
+}