@nextcommerce/campaigns-os 1.57.0 → 1.59.0

package/src/qa-cart-entry.mjs

@@ -35,6 +35,10 @@ export const CART_ENTRY_CODES = Object.freeze({
   ENTRY_CONTROL_MISSING: "cart_entry_control_missing",
   // The control was clicked but the page never reached the checkout URL.
   ENTRY_NO_NAVIGATION: "cart_entry_no_navigation",
+  // A select page's bundle slot shows an empty variant control (size,
+  // colour) with no in-stock option to choose, so its Next would refuse.
+  // Fired before the checkout control is clicked (campaigns-os#667).
+  ENTRY_VARIANT_UNFILLED: "cart_entry_variant_unfilled",
   // The SDK cart held zero items at submit time. Fired before the budget
   // reservation and before the submit click.
   CART_EMPTY_BEFORE_SUBMIT: "cart_empty_before_submit",
@@ -427,6 +431,107 @@ export function chooseCartEntryControl(controls = [], requested = []) {
 // returns the store's `totalQuantity` — and the debugger's cart store second
 // (`window.nextDebug.stores.cart`, present with `?debugger=true`), which is
 // the only public place the line items and their package ids are readable.
+// The variant controls a select page renders per bundle slot: the
+// campaign-cart SDK injects a native select into each slot's
+// [data-next-variant-selectors] (inside a .next-slot-variant-field). The
+// olympus-mv-two-step starter, and pages built from it, hide that select behind
+// a visible os-dropdown (a toggle button plus os-dropdown-item rows carrying
+// `value`); a row click is what sets the select and dispatches `change`.
+export const SLOT_VARIANT_SELECT_SELECTOR = "[data-next-variant-selectors] select, .next-slot-variant-field select";
+export const SLOT_VARIANT_FIELD_SELECTOR = ".next-slot-variant-field";
+export const SLOT_VARIANT_DROPDOWN_TOGGLE_SELECTOR = "os-dropdown .os-card__variant-dropdown-toggle";
+export const SLOT_VARIANT_DROPDOWN_ROW_SELECTOR = "os-dropdown os-dropdown-item";
+
+export const slotVariantKey = ({ bundle_id: bundleId, slot, variant_code: code } = {}) => `${bundleId ?? ""}|${slot}|${code ?? ""}`;
+
+// evaluate() body: the next slot variant action, one per call because a
+// choice can re-render its slot. In document order over the visible slot
+// variant selects (a select counts as visible when it or its field is):
+//   - a field showing a dropdown UI whose key is not in `picked` gets a pick:
+//     the row matching the select's current value when that row is in stock
+//     (so the cart stays what the SDK chose), else the first in-stock row. The
+//     caller clicks the toggle and the row like a shopper, because a page may
+//     count a field as chosen only when a row was clicked. Pre-filled selects
+//     are picked too. Returned as { pick } with the field's index among
+//     SLOT_VARIANT_FIELD_SELECTOR matches and the row's index among the
+//     field's SLOT_VARIANT_DROPDOWN_ROW_SELECTOR matches;
+//   - a select with no dropdown UI is filled here only when it is empty, with
+//     its first in-stock option and input + change dispatched ({ filled });
+//     a pre-filled one is left alone.
+// In stock: enabled, not hidden, non-empty value; for a row also not
+// [disabled], aria-disabled, .next-oos, .next-variant-unavailable or
+// data-available="false", and its native option not disabled. Nothing to
+// choose returns { unfillable } naming the slot; nothing left returns
+// { done: true }.
+export function slotVariantStepScript() {
+  return ({ selector, fieldSelector, toggleSelector, rowSelector, picked = [] }) => {
+    const clean = (value) => String(value || "").replace(/\s+/g, " ").trim();
+    const isVisible = (element) => {
+      if (!element) return false;
+      const rect = element.getBoundingClientRect();
+      const style = getComputedStyle(element);
+      return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden";
+    };
+    const holderOf = (select) => select.closest(fieldSelector) || select.closest("[data-next-variant-selectors]");
+    const visible = Array.from(new Set(document.querySelectorAll(selector)))
+      .filter((select) => !select.disabled && (isVisible(select) || isVisible(holderOf(select))));
+    const slotRoots = Array.from(new Set(visible.map((select) => select.closest("[data-next-variant-selectors]") || holderOf(select))));
+    const fields = Array.from(document.querySelectorAll(fieldSelector));
+    const describe = (select) => {
+      const field = select.closest(fieldSelector);
+      const index = Number.parseInt(field?.getAttribute("data-next-slot-index") ?? "", 10);
+      const root = select.closest("[data-next-variant-selectors]") || holderOf(select);
+      return {
+        bundle_id: clean(field?.getAttribute("data-next-bundle-id")) || null,
+        slot: Number.isFinite(index) ? index + 1 : slotRoots.indexOf(root) + 1,
+        variant_code: clean(select.getAttribute("data-next-variant-code") || select.getAttribute("data-variant-code") || field?.getAttribute("data-next-variant-code") || select.name) || null,
+      };
+    };
+    const keyOf = (info) => `${info.bundle_id ?? ""}|${info.slot}|${info.variant_code ?? ""}`;
+    const optionInStock = (option) => !option.disabled && !option.hidden && clean(option.value) !== "";
+    for (const select of visible) {
+      const info = describe(select);
+      const field = select.closest(fieldSelector);
+      const toggle = field ? Array.from(field.querySelectorAll(toggleSelector)).find(isVisible) : null;
+      if (toggle) {
+        if (picked.includes(keyOf(info))) continue;
+        const rows = Array.from(field.querySelectorAll(rowSelector));
+        // One in-stock rule: a row is in stock when its own markup says so and
+        // its native option (if any) passes optionInStock.
+        const optionsByValue = new Map(Array.from(select.options).map((option) => [clean(option.value), option]));
+        const rowInStock = (row) => {
+          const value = clean(row.getAttribute("value"));
+          if (!value || row.hidden || row.hasAttribute("disabled") || row.getAttribute("aria-disabled") === "true") return false;
+          if (row.classList.contains("next-oos") || row.classList.contains("next-variant-unavailable") || row.getAttribute("data-available") === "false") return false;
+          const option = optionsByValue.get(value);
+          return !option || optionInStock(option);
+        };
+        const current = clean(select.value);
+        const row = (current && rows.find((candidate) => clean(candidate.getAttribute("value")) === current && rowInStock(candidate))) || rows.find(rowInStock);
+        if (!row) return { unfillable: { ...info, options: rows.length, via: "dropdown" } };
+        const fieldIndex = fields.indexOf(field);
+        const rowIndex = rows.indexOf(row);
+        if (fieldIndex < 0 || rowIndex < 0) {
+          return { unfillable: { ...info, options: rows.length, via: "dropdown", detail: `the dropdown ${fieldIndex < 0 ? "field" : "row"} could not be located` } };
+        }
+        return { pick: { ...info, value: clean(row.getAttribute("value")), field_index: fieldIndex, row_index: rowIndex } };
+      }
+      if (clean(select.value) !== "") continue;
+      const option = Array.from(select.options).find(optionInStock);
+      if (!option) return { unfillable: { ...info, options: select.options.length, via: "select" } };
+      select.value = option.value;
+      select.dispatchEvent(new Event("input", { bubbles: true }));
+      select.dispatchEvent(new Event("change", { bubbles: true }));
+      return { filled: { ...info, value: option.value } };
+    }
+    return { done: true };
+  };
+}
+
+export function slotVariantLabel({ bundle_id: bundleId, slot, variant_code: code } = {}) {
+  return `slot ${slot}${bundleId ? ` (bundle "${bundleId}")` : ""}${code ? ` ${code}` : " variant"}`;
+}
+
 // The enriched line list on `getCartData()` is deliberately NOT read: it is
 // always empty on the shipped SDK (campaign-cart#36; see the cart-state
 // verification section of docs/qa-and-test-orders.md), so it would call every

package/src/qa-node.mjs

@@ -37,7 +37,7 @@ import { assessReceiptPurchase } from "./qa-analytics-correctness.mjs";
 import { trackingQaAssertion, trackingRunScopeRows } from "./qa-tracking-params.mjs";
 import { contentParamNotRequestedRows, contentParamQaAssertion } from "./qa-content-params.mjs";
 import { policyLinkNotRequestedRows, policyLinkQaAssertion } from "./qa-policy-links.mjs";
-import { createVerdict, isFindingAssertion, QA_ASSERTION_FAMILY_VOCABULARY, SESSION_ENDING_DISPOSITIONS, SEVERITY, STATUS, validateVerdict } from "./qa-verdict.mjs";
+import { createVerdict, formatTestOrderSummary, isFindingAssertion, QA_ASSERTION_FAMILY_VOCABULARY, SESSION_ENDING_DISPOSITIONS, SEVERITY, STATUS, validateVerdict } from "./qa-verdict.mjs";
 import { normalizeSdkMetaName, lookupSdkIgnoredMetaTag } from "./sdk-meta-tags.mjs";
 import { annotateQaAssertionCauses, formatCauseReportLines, formatCauseTag } from "./finding-cause.mjs";
 import { promoteQaVerdict, writeQaSidecar } from "./qa-sidecar.mjs";
@@ -3577,6 +3577,8 @@ function output(value, args) {
       console.log("This is a passing proof with exceptions. Report these exceptions to the operator; do not clear or waive them, or change markup just to make them pass.");
     }
     console.log(`Counts: ${Object.entries(value.counts).map(([status, count]) => `${count} ${status}`).join(", ")}`);
+    const testOrderSummary = formatTestOrderSummary(value.verdict);
+    if (testOrderSummary) console.log(testOrderSummary);
     printCauseLines(value.verdict);
     printThemeGateLines(value.theme_gate, value.packet_path, value.report_path);
     if (value.commercial) {

package/src/qa-verdict.mjs

@@ -256,7 +256,8 @@ export function summarizePurchaseProof({ verdict = null, proofPolicy = null } =
   return {
     declared_order_path_depth: optionalString(proofPolicy?.order_path_depth),
     declared_typed_card_depth: optionalString(proofPolicy?.typed_card_depth),
-    order_paths_executed: orders.length,
+    order_paths_executed: orders.filter((order) => !isTestOrderRetry(order)).length,
+    test_order_attempts: orders.length,
     orders_created: created.length,
     orders_verified: orders.filter((order) => order.verification?.verified === true).length,
     // null, not false, when nothing ran: "no order was out of test mode" and
@@ -265,6 +266,28 @@ export function summarizePurchaseProof({ verdict = null, proofPolicy = null } =
   };
 }
 
+// A re-run of a planned path is its own test_orders[] entry with `attempt` 2;
+// it is an attempt, not another path. Entries written before `attempt` existed
+// each count as a path, which is what they were counted as then.
+function isTestOrderRetry(order) {
+  const attempt = Number(order?.attempt);
+  return Number.isInteger(attempt) && attempt > 1;
+}
+
+function plural(count, noun) {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+// The human summary line for a run that drove typed-card test orders: planned
+// paths, attempts (a re-run is a second attempt at the same path) and orders
+// the platform created, kept apart so a path that was retried is not read as
+// two paths against the --max-test-orders cap. null when no order path ran.
+export function formatTestOrderSummary(verdict) {
+  const summary = summarizePurchaseProof({ verdict });
+  if (!summary.test_order_attempts) return null;
+  return `Test orders: ${plural(summary.order_paths_executed, "path")}, ${plural(summary.test_order_attempts, "attempt")}, ${plural(summary.orders_created, "order")} created`;
+}
+
 // The browser placeholder-text residue gate (H3.1) emits one assertion per
 // page as `template-residue:<page_id>:placeholder-text`. Both the emitter
 // (qa-browser.mjs) and the stage-ledger summary below build the id from this

package/src/sdk-attribute-index.mjs

@@ -2,7 +2,7 @@
 // checks (#303).
 //
 // Source: the SDK's own source in NextCommerceCo/campaign-cart at tag
-// v0.4.41 (the SDK pin every certified starter family ships today): every
+// v0.4.42 (the SDK pin every certified starter family ships today): every
 // data-next-* name the SDK's non-test TypeScript names as a string, plus every
 // `dataset.next*` property it reads or writes, turned back into its
 // attribute. Only the data-next-* names are kept: the checks that read this
@@ -15,8 +15,8 @@
 // whole from the source at a named tag, never edited by hand.
 //
 //   paths=('src/**/*.ts' ':!src/**/*.test.ts' ':!src/**/tests/**' ':!src/docs/**')
-//   { git -C ../campaign-cart grep -h -oP 'data-next-[a-z0-9]+(?:-[a-z0-9]+)*-?' v0.4.41 -- "${paths[@]}"
-//     git -C ../campaign-cart grep -h -oP 'dataset\.next[A-Z][A-Za-z0-9]*' v0.4.41 -- "${paths[@]}" \
+//   { git -C ../campaign-cart grep -h -oP 'data-next-[a-z0-9]+(?:-[a-z0-9]+)*-?' v0.4.42 -- "${paths[@]}"
+//     git -C ../campaign-cart grep -h -oP 'dataset\.next[A-Z][A-Za-z0-9]*' v0.4.42 -- "${paths[@]}" \
 //       | sed 's/^dataset\.//' | perl -pe 's/([A-Z])/-\L$1/g; s/^/data-/'
 //   } | sort -u
 //
@@ -30,14 +30,15 @@
 // manifests never did (the address block's, data-next-i18n,
 // data-next-bump-section, data-next-button-text, the variant option state).
 // At v0.4.41 it returns every name of the v0.4.38 list this replaces, plus
-// those and data-next-phone-e164 / data-next-phone-country.
+// those and data-next-phone-e164 / data-next-phone-country. At v0.4.42 it
+// returns the same 149 names as at v0.4.41.
 //
 // A name ending in "-" (data-next-class-) is a prefix the SDK reads with any
 // suffix.
 
 import { RELEASED_SDK_VERSION_PATTERN } from "../campaign-spec/dist/index.js";
 
-export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.41";
+export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.42";
 
 export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-accordion",
@@ -364,8 +365,8 @@ export const SDK_TEMPLATE_PLACEHOLDERS = Object.freeze({
 });
 
 // The SDK versions whose renderer files above were verified unchanged from
-// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39, v0.4.40 and v0.4.41, for
+// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39, v0.4.40, v0.4.41 and v0.4.42, for
 // the eight renderer files cited above plus cart-item-list.enhancer.ts and
 // order-item-list.enhancer.ts). A page whose loader pins another version
 // cannot pass the placeholder check.
-export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40", "0.4.41"]);
+export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40", "0.4.41", "0.4.42"]);

package/src/source-html-intake.mjs

@@ -4,7 +4,7 @@ import {
 } from "./source-html-manifest.mjs";
 // Built output of campaign-spec (same import shape as src/page-kit-sdk-version.mjs),
 // so build-time wiring and spec-time analysis share one edge resolver.
-import { checkoutPathFrom, declineRouteTarget, forwardRouteTarget, forwardTargetPage, isCheckoutStepPage } from "../campaign-spec/dist/index.js";
+import { checkoutPathFrom, declineRouteTarget, forwardRouteTarget, forwardTargetPage, isCheckoutStepPage, isPrePaymentPage } from "../campaign-spec/dist/index.js";
 import { isAbsoluteHttpUrl, normalizePageKitRoute, normalizePublicRouteSlug, stripPublicRoutePrefix } from "./route-identity.mjs";
 
 const CPK_PAGE_TYPES = new Set(["product", "checkout", "upsell", "receipt"]);
@@ -570,11 +570,12 @@ function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir,
   const frontmatter = { page_type: pageType };
   if (permalinkRequired) frontmatter.permalink = publicRoute;
 
-  const nextUrl = nextUrlForPage(page, pageById, publicRouteSlug);
-  if (nextUrl) frontmatter.next_url = nextUrl;
+  const forwardUrl = nextUrlForPage(page, pageById, publicRouteSlug);
+  const checkoutFlow = checkoutFlowFrontmatter(page, forwardUrl, { specPages, pageById, publicRouteSlug });
+  if (checkoutFlow) Object.assign(frontmatter, checkoutFlow);
+  else if (forwardUrl) frontmatter.next_url = forwardUrl;
   const declineUrl = declineUrlForPage(page, pageById, publicRouteSlug);
-  if (declineUrl && declineUrl !== nextUrl) frontmatter.decline_url = declineUrl;
-  Object.assign(frontmatter, checkoutFlowFrontmatter(page, { specPages, pageById, publicRouteSlug }));
+  if (declineUrl && declineUrl !== forwardUrl) frontmatter.decline_url = declineUrl;
 
   return {
     target_path: targetPath,
@@ -587,24 +588,32 @@ function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir,
   };
 }
 
-// Multi-step checkout wiring (campaigns-os#641), for any page that leads into a
-// Checkout without being it: a select page, a checkout_step, or a landing page
-// whose forward links reach a Checkout.
-//   success_url  the Checkout's post-payment destination (its own next_url).
-//                The page's next-success-url meta tag carries it, because the
-//                SDK reads that tag for express orders placed on this page; an
-//                express order on step 1 must land on the first upsell, not on
-//                step 2. Forward navigation never uses that tag: a step form
-//                navigates by data-next-checkout-step, a select page by a link.
+// Multi-step checkout wiring (campaigns-os#641) for a select or checkout_step
+// page on a path to a Checkout. The keys follow the starter-template contract
+// (campaign-cart-starter-templates#223). Null for any other page, whose
+// next_url stays its own forward link: a landing page's call-to-action reads
+// next_url, so pointing it past the Checkout would skip payment.
+//   next_url     where a completed order goes: the Checkout's post-payment
+//                destination (its own next_url), the meaning next_url has on a
+//                single-page checkout. The page's next-success-url meta tag
+//                carries it, because the SDK reads that tag for express orders
+//                placed on this page; an express order on step 1 must land on
+//                the first upsell, not on step 2.
+//   next_step    this page's forward link: a step form's
+//                data-next-checkout-step, a select page's checkout link.
 //   step_number  on a checkout_step only: its position among the steps of its
 //                path, from 1, for the form's data-next-step-number.
-function checkoutFlowFrontmatter(page, { specPages, pageById, publicRouteSlug }) {
-  if (!page || page.type === "checkout") return {};
+function checkoutFlowFrontmatter(page, forwardUrl, { specPages, pageById, publicRouteSlug }) {
+  // A path of two or more pages means the page has a resolvable forward link,
+  // so forwardUrl is set; the guard keeps the pair together regardless, never
+  // emitting the Checkout's destination without a next_step to navigate by.
+  if (!isPrePaymentPage(page) || !forwardUrl) return null;
   const path = checkoutPathFrom(specPages, page);
-  if (!path || path.length < 2) return {};
+  if (!path || path.length < 2) return null;
   const out = {};
   const successUrl = nextUrlForPage(path[path.length - 1], pageById, publicRouteSlug);
-  if (successUrl) out.success_url = successUrl;
+  if (successUrl) out.next_url = successUrl;
+  out.next_step = forwardUrl;
   if (isCheckoutStepPage(page)) out.step_number = checkoutStepNumber(page, specPages);
   return out;
 }