@tokenoftrust/storefront-runner 2.4.72 → 2.4.74

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;
+}