@automattic/newspack-blocks 4.33.1 → 4.34.0-alpha.2

package/src/modal-checkout/checkout-button-trigger.js

@@ -22,19 +22,45 @@ export function readCheckoutData( form ) {
 	}
 }
 
+/**
+ * Container Modal_Checkout::render_url_triggered_block() wraps a synthesized
+ * block in. Buttons inside it exist only to serve the URL trigger, so the
+ * resolver considers them after every block the page itself carries.
+ *
+ * @type {string}
+ */
+export const SYNTHESIZED_CONTAINER_SELECTOR = '.newspack-blocks__url-triggered-checkout';
+
+/**
+ * Whether an element belongs to a synthesized (URL-triggered) footer block.
+ *
+ * @param {HTMLElement} element The element to test.
+ *
+ * @return {boolean} Whether the element is inside the synthesized container.
+ */
+const isSynthesized = element => Boolean( element.closest( SYNTHESIZED_CONTAINER_SELECTOR ) );
+
 /**
  * Find a checkout button form matching the requested product.
  *
  * Variation requests are never served by a button locked to a different
- * variation.
+ * variation, and a request without a variation is never served by a locked
+ * button at all: submitting one checks the reader out on its variation, where
+ * the request meant for the reader to pick one.
  *
- * @param {Document|HTMLElement} root        The DOM root to search.
- * @param {string}               productId   The requested product ID.
- * @param {string|null}          variationId Optional. The requested variation ID.
+ * @param {Document|HTMLElement} root                The DOM root to search.
+ * @param {string}               productId           The requested product ID.
+ * @param {string|null}          variationId         Optional. The requested variation ID.
+ * @param {Object}               options             Options.
+ * @param {boolean|null}         options.synthesized Restrict the search: false for
+ *                                                   page-authored buttons only, true
+ *                                                   for synthesized ones only, null
+ *                                                   (default) for both.
  *
  * @return {HTMLFormElement|null} The matching form, or null.
  */
-export function findCheckoutButtonForm( root, productId, variationId = null ) {
+export function findCheckoutButtonForm( root, productId, variationId = null, options = {} ) {
+	const { synthesized = null } = options;
 	const buttons = root.querySelectorAll( '.wp-block-newspack-blocks-checkout-button' );
 	const hasVariation = variationId !== null && variationId !== undefined && String( variationId ) !== '';
 	let match = null;
@@ -42,6 +68,9 @@ export function findCheckoutButtonForm( root, productId, variationId = null ) {
 		if ( match ) {
 			return;
 		}
+		if ( synthesized !== null && isSynthesized( button ) !== synthesized ) {
+			return;
+		}
 		const form = button.querySelector( 'form' );
 		const data = readCheckoutData( form );
 		if ( ! data ) {
@@ -53,6 +82,9 @@ export function findCheckoutButtonForm( root, productId, variationId = null ) {
 		if ( hasVariation && String( data.variation_id ) !== String( variationId ) ) {
 			return;
 		}
+		if ( ! hasVariation && data.variation_id ) {
+			return;
+		}
 		match = form;
 	} );
 	return match;
@@ -66,12 +98,15 @@ export function findCheckoutButtonForm( root, productId, variationId = null ) {
  * whichever variation the reader picks. A locked button was configured for one
  * specific variation and is only used when nothing better exists.
  *
- * @param {Document|HTMLElement} root      The DOM root to search.
- * @param {string}               productId The requested product ID.
+ * @param {Document|HTMLElement} root                The DOM root to search.
+ * @param {string}               productId           The requested product ID.
+ * @param {Object}               options             Options.
+ * @param {boolean|null}         options.synthesized See findCheckoutButtonForm().
  *
  * @return {HTMLFormElement|null} The donor form, or null.
  */
-function findContextDonorForm( root, productId ) {
+function findContextDonorForm( root, productId, options = {} ) {
+	const { synthesized = null } = options;
 	const buttons = root.querySelectorAll( '.wp-block-newspack-blocks-checkout-button' );
 	let fallback = null;
 	let unlocked = null;
@@ -79,6 +114,9 @@ function findContextDonorForm( root, productId ) {
 		if ( unlocked ) {
 			return;
 		}
+		if ( synthesized !== null && isSynthesized( button ) !== synthesized ) {
+			return;
+		}
 		const form = button.querySelector( 'form' );
 		const data = readCheckoutData( form );
 		if ( ! data || String( data.product_id ) !== String( productId ) ) {
@@ -255,34 +293,138 @@ export function copyContextFields( sourceForm, targetForm, fields = PICKER_CONTE
 	} );
 }
 
+/**
+ * Read utm params from a query string, mirroring the server-side prefix match
+ * (Modal_Checkout::merge_request_utm_params()).
+ *
+ * @param {string} search The query string (e.g. window.location.search).
+ *
+ * @return {Object} Map of utm param name → value. Empty values are dropped.
+ */
+export function readUtmParams( search ) {
+	const params = {};
+	new URLSearchParams( search ).forEach( ( value, key ) => {
+		if ( key.startsWith( 'utm' ) && value ) {
+			params[ key ] = value;
+		}
+	} );
+	return params;
+}
+
+/**
+ * Append utm params to a checkout form as hidden fields.
+ *
+ * The modal checkout form GET-submits into its iframe, replacing the landing
+ * URL's query string, and the URL-trigger path strips the params from the
+ * address bar after it fires — so the form's own fields are the only carrier
+ * the checkout request can rely on. A field already on the form wins.
+ *
+ * @param {HTMLFormElement|null} form   The form about to submit.
+ * @param {Object}               params Map of utm param name → value.
+ *
+ * @return {void}
+ */
+export function appendUtmFields( form, params ) {
+	if ( ! form || ! params ) {
+		return;
+	}
+	const doc = form.ownerDocument;
+	Object.keys( params ).forEach( name => {
+		// The name comes from the landing URL, so it must never be interpolated
+		// into a selector — a key carrying selector syntax would throw and abort
+		// the submission. The form's own controls collection checks it safely.
+		if ( ! params[ name ] || form.elements.namedItem( name ) ) {
+			return;
+		}
+		const input = doc.createElement( 'input' );
+		input.type = 'hidden';
+		input.name = name;
+		input.value = params[ name ];
+		form.prepend( input );
+	} );
+}
+
+/**
+ * Link params that only reach the checkout as fields on the submitted form.
+ *
+ * A promotional URL carries these for the block the server synthesizes; when a
+ * page-authored form wins the resolution instead, whichever of them that form
+ * does not carry never reaches the checkout.
+ *
+ * @type {string[]}
+ */
+export const LINK_CONTEXT_PARAMS = [ 'coupon', 'after_success_behavior', 'after_success_url', 'after_success_button_label' ];
+
+/**
+ * Name the link params the resolved form has no field for.
+ *
+ * The trigger submits the form as-is, so a param without a matching field is
+ * dropped — the caller warns instead of letting that happen silently.
+ *
+ * @param {HTMLFormElement|null} form   The form about to be submitted.
+ * @param {string}               search The landing page query string.
+ *
+ * @return {string[]} Names of params the form will not carry.
+ */
+export function getDroppedLinkContext( form, search ) {
+	const params = new URLSearchParams( search );
+	return LINK_CONTEXT_PARAMS.filter( name => params.get( name ) && ! ( form && form.elements.namedItem( name ) ) );
+}
+
 /**
  * Resolve which form a `checkout_button` URL trigger should submit.
  *
- * Strict order: exact button, picker, then explicit product-only fallback.
- * Returning null prevents silent substitution.
+ * Page-authored forms outrank the synthesized footer form at every step, so a
+ * block an editor configured — with its coupon and after-checkout context —
+ * always wins over the copy rendered to serve the trigger. Strict order: exact
+ * page button, picker fed by a page button's context, exact synthesized button,
+ * picker fed by the synthesized context. Returning null prevents silent
+ * substitution.
  *
  * @param {Document|HTMLElement} root        The DOM root to search.
  * @param {string}               productId   The requested product ID.
  * @param {string|null}          variationId Optional. The requested variation ID.
- * @param {Object}               options     Options (see selectPickerForm) plus
- *                                           `allowProductOnlyFallback` (default false).
+ * @param {Object}               options     Options (see selectPickerForm).
  *
  * @return {HTMLFormElement|null} The form to submit, or null.
  */
 export function resolveCheckoutButtonForm( root, productId, variationId, options = {} ) {
-	const { allowProductOnlyFallback = false } = options;
 	const hasVariation = variationId !== null && variationId !== undefined && String( variationId ) !== '';
 
 	if ( ! hasVariation ) {
-		// No variation requested. If several buttons on the page share this
-		// parent product, the first in DOM order is used (along with its
-		// context); the URL gives no signal to prefer one over another.
-		return findCheckoutButtonForm( root, productId, null );
+		// No variation requested. If several unlocked buttons on the page share
+		// this parent product, the first page-authored one in DOM order is used
+		// (along with its context); the synthesized form serves when the page
+		// carries none, including when its only buttons are locked to a
+		// variation — a locked button would check the reader out on that
+		// variation instead of opening the picker the link asks for.
+		return (
+			findCheckoutButtonForm( root, productId, null, { synthesized: false } ) ||
+			findCheckoutButtonForm( root, productId, null, { synthesized: true } )
+		);
 	}
 
-	const exact = findCheckoutButtonForm( root, productId, variationId );
-	if ( exact ) {
-		return exact;
+	const exactPage = findCheckoutButtonForm( root, productId, variationId, { synthesized: false } );
+	if ( exactPage ) {
+		return exactPage;
+	}
+
+	// A page button for this product exists but none is locked to the requested
+	// variation: let the picker serve it with that page button's context. This
+	// deliberately outranks a synthesized exact match — the page block's coupon
+	// and after-checkout settings are the editor's, and they keep applying.
+	const pageDonor = findContextDonorForm( root, productId, { synthesized: false } );
+	if ( pageDonor ) {
+		const pagePicker = selectPickerForm( root, productId, variationId, options );
+		if ( pagePicker ) {
+			copyContextFields( pageDonor, pagePicker );
+			return pagePicker;
+		}
+	}
+
+	const exactSynthesized = findCheckoutButtonForm( root, productId, variationId, { synthesized: true } );
+	if ( exactSynthesized ) {
+		return exactSynthesized;
 	}
 
 	const picker = selectPickerForm( root, productId, variationId, options );
@@ -298,9 +440,5 @@ export function resolveCheckoutButtonForm( root, productId, variationId, options
 		return picker;
 	}
 
-	if ( allowProductOnlyFallback ) {
-		return findCheckoutButtonForm( root, productId, null );
-	}
-
 	return null;
 }

package/src/modal-checkout/checkout-button-trigger.test.js

@@ -9,7 +9,11 @@ import {
 	resolveCheckoutButtonForm,
 	copyContextFields,
 	applyContextFields,
+	readUtmParams,
+	appendUtmFields,
+	getDroppedLinkContext,
 	PICKER_CONTEXT_FIELDS,
+	SYNTHESIZED_CONTAINER_SELECTOR,
 } from './checkout-button-trigger';
 
 const VARIATION_MODAL_CLASS_PREFIX = 'newspack-blocks__modal-variation';
@@ -93,8 +97,16 @@ describe( 'findCheckoutButtonForm', () => {
 		expect( findCheckoutButtonForm( root, '1406', '1407' ) ).toBeNull();
 	} );
 
-	it( 'matches by product_id only when no variation is requested', () => {
+	// A request without a variation means the reader picks one, so a button locked
+	// to a single variation cannot serve it: submitting that form checks the
+	// reader out on the locked variation instead of opening the picker.
+	it( 'does not match a variation-locked button when no variation is requested', () => {
 		const root = render( checkoutButton( { product_id: '1406', variation_id: '1408', is_variable: true } ) );
+		expect( findCheckoutButtonForm( root, '1406', null ) ).toBeNull();
+	} );
+
+	it( 'matches an unlocked button by product_id when no variation is requested', () => {
+		const root = render( checkoutButton( { product_id: '1406', is_variable: true } ) );
 		const form = root.querySelector( 'form' );
 		expect( findCheckoutButtonForm( root, '1406', null ) ).toBe( form );
 	} );
@@ -180,7 +192,9 @@ describe( 'resolveCheckoutButtonForm', () => {
 		expect( root.querySelector( 'input[value="158"]' ).checked ).toBe( true );
 	} );
 
-	it( 'returns null for an invalid variation when product-only fallback is off (default)', () => {
+	// Substituting the product-only button would check the reader out on
+	// something other than what the link asked for.
+	it( 'returns null for a variation no button or picker can serve', () => {
 		const root = render( checkoutButton( { product_id: '158' }, 'Checkout' ) );
 		expect( resolveCheckoutButtonForm( root, '158', '160', PICKER_OPTIONS ) ).toBeNull();
 	} );
@@ -190,16 +204,20 @@ describe( 'resolveCheckoutButtonForm', () => {
 		expect( resolveCheckoutButtonForm( root, '158', '158', PICKER_OPTIONS ) ).toBeNull();
 	} );
 
-	it( 'returns the product-only button for an invalid variation only when fallback is explicitly enabled', () => {
-		const root = render( checkoutButton( { product_id: '158' }, 'Checkout' ) );
-		const buttonForm = root.querySelector( 'form' );
-		expect( resolveCheckoutButtonForm( root, '158', '160', { ...PICKER_OPTIONS, allowProductOnlyFallback: true } ) ).toBe( buttonForm );
+	// A "let the reader choose" link carries the parent id only. A page button
+	// locked to one variation must not catch it, or the reader is checked out on
+	// that variation with no picker.
+	it( 'serves an unlocked page button for a no-variation link even when a locked one precedes it', () => {
+		const locked = checkoutButton( { product_id: '1406', variation_id: '1408', is_variable: true }, 'Annual' );
+		const unlocked = checkoutButton( { product_id: '1406', is_variable: true }, 'Subscribe' );
+		const root = render( locked + unlocked );
+		const unlockedForm = root.querySelectorAll( '.wp-block-newspack-blocks-checkout-button form' )[ 1 ];
+		expect( resolveCheckoutButtonForm( root, '1406', null, PICKER_OPTIONS ) ).toBe( unlockedForm );
 	} );
 
-	it( 'matches a checkout button by product_id when no variation is requested', () => {
+	it( 'returns null for a no-variation link when the page carries only locked buttons and nothing is synthesized', () => {
 		const root = render( checkoutButton( { product_id: '1406', variation_id: '1408', is_variable: true } ) );
-		const buttonForm = root.querySelector( 'form' );
-		expect( resolveCheckoutButtonForm( root, '1406', null, PICKER_OPTIONS ) ).toBe( buttonForm );
+		expect( resolveCheckoutButtonForm( root, '1406', null, PICKER_OPTIONS ) ).toBeNull();
 	} );
 
 	it( 'returns null without throwing when nothing matches', () => {
@@ -270,6 +288,59 @@ describe( 'resolveCheckoutButtonForm', () => {
 	} );
 } );
 
+describe( 'resolveCheckoutButtonForm — synthesized form demotion', () => {
+	const synthesized = html => `<div class="${ SYNTHESIZED_CONTAINER_SELECTOR.slice( 1 ) }" style="display:none">${ html }</div>`;
+
+	it( 'prefers a page-authored button over an earlier synthesized one', () => {
+		// The synthesized form is rendered first to prove the preference is not
+		// DOM order.
+		const root = render( synthesized( checkoutButton( { product_id: '1406' }, 'Synth' ) ) + checkoutButton( { product_id: '1406' }, 'Page' ) );
+		const pageForm = root.querySelectorAll( '.wp-block-newspack-blocks-checkout-button form' )[ 1 ];
+		expect( resolveCheckoutButtonForm( root, '1406', null, PICKER_OPTIONS ) ).toBe( pageForm );
+	} );
+
+	// The page button is locked to Annual; the link asks for the parent. The
+	// synthesized parent button is the one that opens the picker, so it wins
+	// even though a page-authored button for the product exists.
+	it( 'serves the synthesized parent button for a no-variation link when the page offers only locked buttons', () => {
+		const pageLocked = checkoutButton( { product_id: '1406', variation_id: '1408', is_variable: true }, 'Annual' );
+		const synthParent = synthesized( checkoutButton( { product_id: '1406', is_variable: true }, 'Subscribe' ) );
+		const root = render( pageLocked + synthParent + variationPicker( '1406', [ '1407', '1408' ] ) );
+		const synthForm = root.querySelector( `${ SYNTHESIZED_CONTAINER_SELECTOR } form` );
+		expect( resolveCheckoutButtonForm( root, '1406', null, PICKER_OPTIONS ) ).toBe( synthForm );
+	} );
+
+	// The page block's coupon and after-checkout settings are the editor's, so a
+	// synthesized form locked to the requested variation must not outrank them.
+	it( 'lets the picker with page context outrank a synthesized exact variation match', () => {
+		const pageUnlocked = `<div class="wp-block-newspack-blocks-checkout-button"><form data-checkout='${ JSON.stringify( {
+			product_id: '1406',
+			is_variable: true,
+		} ) }'><input type="hidden" name="coupon" value="PAGE20"><button type="submit">Subscribe</button></form></div>`;
+		const synthLocked = synthesized(
+			`<div class="wp-block-newspack-blocks-checkout-button"><form data-checkout='${ JSON.stringify( {
+				product_id: '1406',
+				variation_id: '1407',
+				is_variable: true,
+			} ) }'><input type="hidden" name="coupon" value="URL5"><button type="submit">Complete</button></form></div>`
+		);
+		const root = render( pageUnlocked + synthLocked + variationPicker( '1406', [ '1407', '1408' ] ) );
+		const pickerForm = root.querySelector( `.${ VARIATION_MODAL_CLASS_PREFIX } form` );
+
+		const result = resolveCheckoutButtonForm( root, '1406', '1407', PICKER_OPTIONS );
+
+		expect( result ).toBe( pickerForm );
+		expect( pickerForm.querySelector( 'input[name="coupon"]' ).value ).toBe( 'PAGE20' );
+	} );
+
+	it( 'serves the synthesized exact match when the page has no button for the product', () => {
+		const synthLocked = synthesized( checkoutButton( { product_id: '1406', variation_id: '1407', is_variable: true } ) );
+		const root = render( synthLocked + variationPicker( '1406', [ '1407', '1408' ] ) );
+		const synthForm = root.querySelector( `${ SYNTHESIZED_CONTAINER_SELECTOR } form` );
+		expect( resolveCheckoutButtonForm( root, '1406', '1407', PICKER_OPTIONS ) ).toBe( synthForm );
+	} );
+} );
+
 describe( 'copyContextFields', () => {
 	it( 'copies present source fields, skips missing ones, and does not overwrite existing target fields', () => {
 		const root = render(
@@ -443,3 +514,72 @@ describe( 'PICKER_CONTEXT_FIELDS', () => {
 		);
 	} );
 } );
+
+describe( 'readUtmParams', () => {
+	it( 'keeps utm-prefixed params with values, mirroring the server-side match', () => {
+		expect( readUtmParams( '?utm_source=newsletter&utm_campaign=spring&coupon=NOPE&utm_medium=' ) ).toEqual( {
+			utm_source: 'newsletter',
+			utm_campaign: 'spring',
+		} );
+	} );
+
+	it( 'returns an empty map for an empty query string', () => {
+		expect( readUtmParams( '' ) ).toEqual( {} );
+	} );
+} );
+
+describe( 'appendUtmFields', () => {
+	it( 'appends a hidden field per utm param', () => {
+		const root = render( checkoutButton( { product_id: '1406' } ) );
+		const form = root.querySelector( 'form' );
+		appendUtmFields( form, { utm_source: 'newsletter', utm_campaign: 'spring' } );
+		expect( form.querySelector( 'input[name="utm_source"]' ).value ).toBe( 'newsletter' );
+		expect( form.querySelector( 'input[name="utm_campaign"]' ).value ).toBe( 'spring' );
+	} );
+
+	it( 'never overwrites a field the form already carries', () => {
+		const root = render( checkoutButton( { product_id: '1406' } ) );
+		const form = root.querySelector( 'form' );
+		form.insertAdjacentHTML( 'beforeend', '<input type="hidden" name="utm_source" value="block-value">' );
+		appendUtmFields( form, { utm_source: 'url-value' } );
+		expect( form.querySelectorAll( 'input[name="utm_source"]' ) ).toHaveLength( 1 );
+		expect( form.querySelector( 'input[name="utm_source"]' ).value ).toBe( 'block-value' );
+	} );
+
+	it( 'does not throw on a null form or missing params', () => {
+		expect( () => appendUtmFields( null, { utm_source: 'x' } ) ).not.toThrow();
+		expect( () => appendUtmFields( document.createElement( 'form' ), null ) ).not.toThrow();
+	} );
+
+	// Param names come straight from the landing URL, so one carrying selector
+	// syntax must not break the submission.
+	it( 'tolerates a field name carrying selector syntax', () => {
+		const root = render( checkoutButton( { product_id: '1406' } ) );
+		const form = root.querySelector( 'form' );
+		expect( () => appendUtmFields( form, { 'utm"]': 'x' } ) ).not.toThrow();
+		expect( form.elements.namedItem( 'utm"]' ).value ).toBe( 'x' );
+	} );
+} );
+
+describe( 'getDroppedLinkContext', () => {
+	it( 'names the link params the resolved form has no field for', () => {
+		const root = render( checkoutButton( { product_id: '1406' } ) );
+		const form = root.querySelector( 'form' );
+		expect( getDroppedLinkContext( form, '?checkout=1&coupon=SPRING20&after_success_url=https%3A%2F%2Fsite.test%2Fwelcome' ) ).toEqual( [
+			'coupon',
+			'after_success_url',
+		] );
+	} );
+
+	it( 'is empty when the form carries the fields or the URL names none', () => {
+		const root = render( checkoutButton( { product_id: '1406' } ) );
+		const form = root.querySelector( 'form' );
+		form.insertAdjacentHTML( 'beforeend', '<input type="hidden" name="coupon" value="PAGE20">' );
+		expect( getDroppedLinkContext( form, '?checkout=1&coupon=SPRING20' ) ).toEqual( [] );
+		expect( getDroppedLinkContext( form, '?checkout=1&product_id=1406' ) ).toEqual( [] );
+	} );
+
+	it( 'counts every named param as dropped without a form', () => {
+		expect( getDroppedLinkContext( null, '?coupon=X&after_success_behavior=custom' ) ).toEqual( [ 'coupon', 'after_success_behavior' ] );
+	} );
+} );

package/src/modal-checkout/modal.js

@@ -24,7 +24,14 @@ import {
 	getCheckoutData,
 	getFormattedAmount,
 } from './utils';
-import { resolveCheckoutButtonForm, readCheckoutData, applyContextFields } from './checkout-button-trigger';
+import {
+	resolveCheckoutButtonForm,
+	readCheckoutData,
+	applyContextFields,
+	appendUtmFields,
+	readUtmParams,
+	getDroppedLinkContext,
+} from './checkout-button-trigger';
 import { resolveDonationTrigger } from './donate-trigger';
 import { TIERS_BASED_READY_EVENT } from '../shared/js/tiers-based-ready';
 import { applyCtaAttribution } from '../shared/js/cta-attribution';
@@ -285,6 +292,12 @@ domReady( () => {
 		newspackBlocksModal?.is_registration_required &&
 		window?.newspackReaderActivation?.openAuthModal;
 
+	// Snapshot the landing page's utm params: the form's own GET submission
+	// replaces the query string entirely, so the request the checkout sees
+	// carries only what rides the form. Captured once, applied to every form
+	// (direct, donate, picker) at submit time.
+	const landingUtmParams = readUtmParams( window.location.search );
+
 	/**
 	 * Handle checkout form submit.
 	 *
@@ -305,6 +318,11 @@ domReady( () => {
 		// inside a gate. Must run BEFORE getCheckoutData(), which snapshots the form.
 		applyCtaAttribution( form );
 
+		// Carry the landing page's utm params into the checkout request itself, so
+		// Modal_Checkout::merge_request_utm_params() reads them from $_GET instead
+		// of depending on the referer.
+		appendUtmFields( form, landingUtmParams );
+
 		const checkoutData = getCheckoutData( form );
 
 		const isDonateBlock = checkoutData.newspack_donate;
@@ -887,6 +905,18 @@ domReady( () => {
 			iframeName: IFRAME_NAME,
 		} );
 		if ( form ) {
+			// A page-authored form wins with its own context; say so when that
+			// drops something the link carried, instead of applying list price
+			// or the default thank-you behavior with no trace.
+			const dropped = getDroppedLinkContext( form, window.location.search );
+			if ( dropped.length ) {
+				// eslint-disable-next-line no-console
+				console.warn(
+					`Newspack modal checkout: the resolved checkout form does not carry ${ dropped.join(
+						', '
+					) } from the URL. The page block's own settings apply instead.`
+				);
+			}
 			triggerFormSubmit( form );
 			return true;
 		}