@automattic/newspack-blocks 4.31.1 → 4.32.0-alpha.2

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

@@ -0,0 +1,233 @@
+/**
+ * Tests for the donate URL trigger resolution helpers.
+ */
+
+import { resolveDonationTrigger, validateDonationTriggerParams } from './donate-trigger';
+import { TIERS_BASED_READY_EVENT, TIERS_BASED_READY_ATTRIBUTE } from '../shared/js/tiers-based-ready';
+
+/**
+ * Build a tiers-based Donate block markup string, mirroring
+ * Newspack_Blocks_Donate_Renderer_Tiers_Based::render output.
+ *
+ * @param {Object}   options             Options.
+ * @param {string[]} options.frequencies Enabled frequency slugs. Tab buttons render only when more than one.
+ * @param {string}   options.defaultFreq The block's default (initially selected) frequency.
+ * @param {Object}   options.amounts     Map of frequency slug => array of tier amounts.
+ * @param {boolean}  options.ready       Whether the tiersBased view script marked the block initialized.
+ * @return {string} HTML.
+ */
+const tieredBlock = ( {
+	frequencies = [ 'month', 'year' ],
+	defaultFreq = 'month',
+	amounts = { month: [ 7, 15, 30 ], year: [ 84, 180, 360 ] },
+	ready = true,
+} = {} ) => {
+	const readyAttr = ready ? ` ${ TIERS_BASED_READY_ATTRIBUTE }` : '';
+	const tabs =
+		frequencies.length > 1
+			? `<div class="wpbnbd__tiers__selection">${ frequencies
+					.map( slug => `<button type="button" data-frequency-slug="${ slug }" class="wpbnbd__button">${ slug }</button>` )
+					.join( '' ) }</div>`
+			: '';
+	const tiers = amounts[ defaultFreq ]
+		.map( ( amount, index ) => {
+			const spans = frequencies
+				.map(
+					slug =>
+						`<span data-frequency-slug="${ slug }" data-amount="${ amounts[ slug ][ index ] }" data-tier-index="${ index }">$${ amounts[ slug ][ index ] }</span>`
+				)
+				.join( '' );
+			return `<div class="wpbnbd__tiers__tier"><div class="wpbnbd__tiers__amount"><span>${ spans }</span></div><button type="submit" name="donation_value_${ defaultFreq }" value="${ amount }" data-tier-index="${ index }">Donate</button></div>`;
+		} )
+		.join( '' );
+	return `<div class="wpbnbd wpbnbd--platform-wc wpbnbd--tiers-based"${ readyAttr }><form data-is-init-form><input type="hidden" name="donation_frequency" value="${ defaultFreq }">${ tabs }<div class="wpbnbd__tiers__options">${ tiers }</div></form></div>`;
+};
+
+/**
+ * Build a frequency-based Donate block markup string, mirroring
+ * Newspack_Blocks_Donate_Renderer_Frequency_Based::render output.
+ *
+ * @param {Object}   options             Options.
+ * @param {string[]} options.frequencies Enabled frequency slugs.
+ * @param {Object}   options.amounts     Map of frequency slug => array of amounts.
+ * @param {boolean}  options.untiered    Render the untiered variant instead of amount radios.
+ * @return {string} HTML.
+ */
+const frequencyBlock = ( {
+	frequencies = [ 'once', 'month', 'year' ],
+	amounts = { once: [ 7, 15, 30 ], month: [ 7, 15, 30 ], year: [ 84, 180, 360 ] },
+	untiered = false,
+} = {} ) => {
+	const panels = frequencies
+		.map( slug => {
+			const freqRadio = `<input type="radio" name="donation_frequency" value="${ slug }">`;
+			if ( untiered ) {
+				return `${ freqRadio }<input type="number" name="donation_value_${ slug }_untiered" value="${ amounts[ slug ][ 0 ] }">`;
+			}
+			const amountRadios = amounts[ slug ]
+				.map( amount => `<input type="radio" name="donation_value_${ slug }" value="${ amount }">` )
+				.join( '' );
+			return `${ freqRadio }${ amountRadios }<input type="radio" name="donation_value_${ slug }" value="other"><input type="number" name="donation_value_${ slug }_other">`;
+		} )
+		.join( '' );
+	return `<div class="wpbnbd wpbnbd--platform-wc wpbnbd--frequency-based"><form>${ panels }<button type="submit">Donate</button></form></div>`;
+};
+
+const render = html => {
+	document.body.innerHTML = html;
+	return document.body;
+};
+
+afterEach( () => {
+	document.body.innerHTML = '';
+} );
+
+describe( 'validateDonationTriggerParams', () => {
+	it( 'accepts a tiered layout with a known frequency and integer amount', () => {
+		expect( validateDonationTriggerParams( 'tiered', 'month', '15' ) ).toBe( true );
+	} );
+
+	it( 'accepts a decimal amount', () => {
+		expect( validateDonationTriggerParams( 'untiered', 'year', '15.50' ) ).toBe( true );
+	} );
+
+	it( 'accepts amount "other" for the frequency layout only', () => {
+		expect( validateDonationTriggerParams( 'frequency', 'once', 'other' ) ).toBe( true );
+		expect( validateDonationTriggerParams( 'tiered', 'once', 'other' ) ).toBe( false );
+		expect( validateDonationTriggerParams( 'untiered', 'once', 'other' ) ).toBe( false );
+	} );
+
+	it( 'rejects an unknown layout', () => {
+		expect( validateDonationTriggerParams( 'banana', 'month', '15' ) ).toBe( false );
+	} );
+
+	it( 'rejects an unknown frequency', () => {
+		expect( validateDonationTriggerParams( 'tiered', 'weekly', '15' ) ).toBe( false );
+	} );
+
+	it( 'rejects selector-breaking values', () => {
+		expect( validateDonationTriggerParams( 'tiered', 'month"]', '15' ) ).toBe( false );
+		expect( validateDonationTriggerParams( 'tiered', 'month', '15"][name="x' ) ).toBe( false );
+	} );
+} );
+
+describe( 'resolveDonationTrigger — tiered layout', () => {
+	it( 'resolves a non-default frequency to the tab button and tier index', () => {
+		const root = render( tieredBlock() );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'year', amount: '180' } );
+		expect( resolution.status ).toBe( 'tiered' );
+		expect( resolution.form ).toBe( root.querySelector( 'form' ) );
+		expect( resolution.frequencyButton ).toBe( root.querySelector( 'button[data-frequency-slug="year"]' ) );
+		expect( resolution.tierIndex ).toBe( 1 );
+	} );
+
+	it( 'resolves a single-frequency block without a tab button when the frequency matches', () => {
+		const root = render( tieredBlock( { frequencies: [ 'month' ], amounts: { month: [ 7, 15, 30 ] } } ) );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'month', amount: '15' } );
+		expect( resolution.status ).toBe( 'tiered' );
+		expect( resolution.frequencyButton ).toBeNull();
+		expect( resolution.tierIndex ).toBe( 1 );
+	} );
+
+	it( 'does not match a single-frequency block for a different frequency', () => {
+		const root = render( tieredBlock( { frequencies: [ 'month' ], amounts: { month: [ 7, 15, 30 ] } } ) );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'year', amount: '15' } );
+		expect( resolution.status ).toBe( 'no-match' );
+	} );
+
+	it( 'reports a matching block whose view script has not initialized as not ready', () => {
+		const root = render( tieredBlock( { ready: false } ) );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'year', amount: '180' } );
+		expect( resolution.status ).toBe( 'not-ready' );
+		expect( resolution.form ).toBe( root.querySelector( 'form' ) );
+	} );
+
+	it( 'prefers a later initialized block over an earlier one that never initialized', () => {
+		const root = render( tieredBlock( { ready: false } ) + tieredBlock() );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'year', amount: '180' } );
+		expect( resolution.status ).toBe( 'tiered' );
+		expect( resolution.form ).toBe( root.querySelectorAll( 'form' )[ 1 ] );
+	} );
+
+	it( 'reports not-ready, carrying the first such form, only when no initialized block matches', () => {
+		const root = render( tieredBlock( { ready: false } ) + tieredBlock( { ready: false } ) );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'year', amount: '180' } );
+		expect( resolution.status ).toBe( 'not-ready' );
+		expect( resolution.form ).toBe( root.querySelectorAll( 'form' )[ 0 ] );
+	} );
+
+	it( 'resolves after the tiers view marks the block ready, matching the ready-event contract', () => {
+		const root = render( tieredBlock( { ready: false } ) );
+		expect( resolveDonationTrigger( root, { layout: 'tiered', frequency: 'year', amount: '180' } ).status ).toBe( 'not-ready' );
+		// What the tiers-based view does when it initializes (see view.ts):
+		// stamp the container, then announce readiness so waiting triggers retry.
+		expect( TIERS_BASED_READY_EVENT ).toBe( 'newspack-tiers-based-ready' );
+		expect( TIERS_BASED_READY_ATTRIBUTE ).toBe( 'data-tiers-based-ready' );
+		root.querySelector( '.wpbnbd--tiers-based' ).setAttribute( TIERS_BASED_READY_ATTRIBUTE, '' );
+		const retried = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'year', amount: '180' } );
+		expect( retried.status ).toBe( 'tiered' );
+	} );
+
+	it( 'returns no-match for an amount no tier offers, without mutating the form', () => {
+		const root = render( tieredBlock() );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'year', amount: '999' } );
+		expect( resolution.status ).toBe( 'no-match' );
+		expect( root.querySelector( 'input[name="donation_frequency"]' ).value ).toBe( 'month' );
+		expect( root.querySelector( 'button[type="submit"]' ).getAttribute( 'name' ) ).toBe( 'donation_value_month' );
+	} );
+
+	it( 'picks the first matching form in DOM order, skipping non-matching forms', () => {
+		const root = render( tieredBlock( { frequencies: [ 'month' ], amounts: { month: [ 7, 15, 30 ] } } ) + tieredBlock() );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'year', amount: '180' } );
+		expect( resolution.status ).toBe( 'tiered' );
+		expect( resolution.form ).toBe( root.querySelectorAll( 'form' )[ 1 ] );
+	} );
+
+	it( 'never acts on a frequency-based form', () => {
+		const root = render( frequencyBlock() );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'month', amount: '15' } );
+		expect( resolution.status ).toBe( 'no-match' );
+	} );
+
+	it( 'rejects invalid parameters before touching the DOM', () => {
+		const root = render( tieredBlock() );
+		const resolution = resolveDonationTrigger( root, { layout: 'tiered', frequency: 'month"]', amount: '15' } );
+		expect( resolution.status ).toBe( 'invalid-params' );
+	} );
+} );
+
+describe( 'resolveDonationTrigger — frequency and untiered layouts', () => {
+	it( 'resolves the frequency layout to its frequency and amount inputs', () => {
+		const root = render( frequencyBlock() );
+		const resolution = resolveDonationTrigger( root, { layout: 'frequency', frequency: 'year', amount: '180' } );
+		expect( resolution.status ).toBe( 'frequency' );
+		expect( resolution.frequencyInput ).toBe( root.querySelector( 'input[name="donation_frequency"][value="year"]' ) );
+		expect( resolution.amountInput ).toBe( root.querySelector( 'input[name="donation_value_year"][value="180"]' ) );
+	} );
+
+	it( 'resolves amount "other" to the other radio', () => {
+		const root = render( frequencyBlock() );
+		const resolution = resolveDonationTrigger( root, { layout: 'frequency', frequency: 'once', amount: 'other' } );
+		expect( resolution.status ).toBe( 'frequency' );
+		expect( resolution.amountInput ).toBe( root.querySelector( 'input[name="donation_value_once"][value="other"]' ) );
+	} );
+
+	it( 'resolves the untiered layout to the untiered amount input', () => {
+		const root = render( frequencyBlock( { untiered: true } ) );
+		const resolution = resolveDonationTrigger( root, { layout: 'untiered', frequency: 'month', amount: '25' } );
+		expect( resolution.status ).toBe( 'untiered' );
+		expect( resolution.amountInput ).toBe( root.querySelector( 'input[name="donation_value_month_untiered"]' ) );
+	} );
+
+	it( 'never acts on a tiered form', () => {
+		const root = render( tieredBlock() );
+		const resolution = resolveDonationTrigger( root, { layout: 'frequency', frequency: 'month', amount: '15' } );
+		expect( resolution.status ).toBe( 'no-match' );
+	} );
+
+	it( 'returns no-match when the page has no donate forms', () => {
+		const root = render( '<p>No blocks here.</p>' );
+		const resolution = resolveDonationTrigger( root, { layout: 'frequency', frequency: 'month', amount: '15' } );
+		expect( resolution.status ).toBe( 'no-match' );
+	} );
+} );

package/src/modal-checkout/index.js

@@ -94,6 +94,7 @@ import { domReady, onCheckoutPlaceOrderProcessing } from './utils';
 
 				const $coupon = $( 'form.modal_checkout_coupon' );
 				const $nyp = $( 'form.modal_checkout_nyp' );
+				const $quantity = $( 'form.modal_checkout_quantity' );
 				const $checkout_continue = $( '#checkout_continue' );
 				const $customer_details = $( '#customer_details' );
 				const $after_customer_details = $( '#after_customer_details' );
@@ -480,6 +481,90 @@ import { domReady, onCheckoutPlaceOrderProcessing } from './utils';
 					$nyp.on( 'submit', handleNYPFormSubmit );
 				}
 
+				/**
+				 * Replace the quantity form's result line, and mark the field when the
+				 * server refused the change.
+				 *
+				 * @param {boolean} success
+				 * @param {string}  message
+				 */
+				function showQuantityResult( success, message ) {
+					$quantity.find( '.result' ).remove();
+					$quantity.append(
+						`<p class="result ${ CLASS_PREFIX }__helper-text ${ ! success ? CLASS_PREFIX + '__inline-error' : '' }">` + message + '</p>'
+					);
+					$quantity.find( 'h3, input[name="quantity"]' ).toggleClass( 'newspack-ui__field-error', ! success );
+				}
+
+				/**
+				 * Handle quantity form submission.
+				 *
+				 * On success the order review is refreshed to show the new total, and the
+				 * `#modal-checkout-product-details` data carrier is rewritten from the
+				 * response — `update_checkout` only replaces the review-order table and
+				 * payment box, and the carrier sits outside both.
+				 *
+				 * On failure the server has already put the original line item back, so
+				 * the review still matches the cart and must be left alone.
+				 *
+				 * @param {Event} ev
+				 */
+				function handleQuantityFormSubmit( ev ) {
+					ev.preventDefault();
+					const blocked = blockForm( $quantity );
+					if ( ! blocked ) {
+						return false;
+					}
+					const input = $quantity.find( 'input[name="quantity"]' );
+					input.attr( 'disabled', true );
+					const data = {
+						_ajax_nonce: newspackBlocksModalCheckout.quantity_nonce,
+						action: 'process_quantity_request',
+						quantity: input.val(),
+						product_id: $quantity.find( 'input[name="product_id"]' ).val(),
+					};
+					$.ajax( {
+						type: 'POST',
+						url: newspackBlocksModalCheckout.ajax_url,
+						data,
+						success: response => {
+							// A malformed request returns bare (`0`), so there is no envelope
+							// to read and nothing the reader could act on.
+							if ( ! response || typeof response.success === 'undefined' ) {
+								showQuantityResult( false, newspackBlocksModalCheckout.quantity_error );
+								return;
+							}
+							const { success, data: res } = response;
+							clearNotices();
+							showQuantityResult( success, res?.message || newspackBlocksModalCheckout.quantity_error );
+							if ( success ) {
+								if ( res.checkout_data ) {
+									$( '#modal-checkout-product-details' ).attr( 'data-checkout', JSON.stringify( res.checkout_data ) );
+									// The server may accept a quantity other than the one asked
+									// for — a product sold in bounds clamps to them. Show the
+									// count the reader is about to pay for, not the one they typed.
+									if ( res.checkout_data.quantity ) {
+										input.val( res.checkout_data.quantity );
+									}
+								}
+								$( document.body ).trigger( 'update_checkout', { update_shipping_method: false } );
+							} else {
+								input.focus();
+							}
+						},
+						// An expired nonce dies with a 403, which never reaches success:.
+						error: () => showQuantityResult( false, newspackBlocksModalCheckout.quantity_error ),
+						complete: () => {
+							unblockForm( $quantity );
+							input.attr( 'disabled', false );
+							input.focus();
+						},
+					} );
+				}
+				if ( $quantity.length ) {
+					$quantity.on( 'submit', handleQuantityFormSubmit );
+				}
+
 				/**
 				 * Handle form 1st step submission.
 				 *
@@ -515,6 +600,9 @@ import { domReady, onCheckoutPlaceOrderProcessing } from './utils';
 						if ( $nyp.length ) {
 							$nyp.hide();
 						}
+						if ( $quantity.length ) {
+							$quantity.hide();
+						}
 						$customer_details.show();
 						$after_customer_details.hide();
 						$customer_details.find( 'input' ).first().focus();
@@ -550,6 +638,9 @@ import { domReady, onCheckoutPlaceOrderProcessing } from './utils';
 						if ( $nyp.length ) {
 							$nyp.show();
 						}
+						if ( $quantity.length ) {
+							$quantity.show();
+						}
 						$customer_details.hide();
 						$after_customer_details.show();
 						renderCheckoutDetails();

package/src/modal-checkout/modal.js

@@ -25,6 +25,8 @@ import {
 	getFormattedAmount,
 } from './utils';
 import { resolveCheckoutButtonForm, readCheckoutData, applyContextFields } 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';
 
 const CLASS_PREFIX = newspackBlocksModal.newspack_class_prefix;
@@ -752,57 +754,123 @@ domReady( () => {
 			} );
 		} );
 
+	/**
+	 * Query params a modal checkout URL trigger consumes (see
+	 * handleModalCheckoutUrlParams). Only these are stripped after a successful
+	 * trigger — unrelated params (UTMs, plain-permalink ids) and the hash
+	 * survive.
+	 */
+	const CHECKOUT_TRIGGER_PARAMS = [ 'checkout', 'type', 'layout', 'frequency', 'amount', 'other', 'product_id', 'variation_id' ];
+
+	/**
+	 * Remove the modal checkout trigger params from the address bar.
+	 */
+	const stripCheckoutUrlParams = () => {
+		const url = new URL( window.location.href );
+		CHECKOUT_TRIGGER_PARAMS.forEach( param => url.searchParams.delete( param ) );
+		window.history.replaceState( null, null, url.href );
+	};
+
 	/**
 	 * Handle donation form triggers.
 	 *
+	 * Resolution (which form, which tier) is delegated to resolveDonationTrigger,
+	 * which validates the URL params and never mutates the DOM, so a trigger that
+	 * can't complete leaves the page untouched. Only the first form in DOM order
+	 * that fully satisfies the trigger is acted on.
+	 *
 	 * @param {string}      layout    The donation layout.
 	 * @param {string}      frequency The donation frequency.
 	 * @param {string}      amount    The donation amount.
 	 * @param {string|null} other     Optional. The custom amount when other is selected.
+	 *
+	 * @return {boolean} Whether a donation form was triggered.
 	 */
 	const triggerDonationForm = ( layout, frequency, amount, other = null ) => {
-		let form;
-		document.querySelectorAll( '.wpbnbd.wpbnbd--platform-wc form' ).forEach( donationForm => {
-			const frequencyInput = donationForm.querySelector( `input[name="donation_frequency"][value="${ frequency }"]` );
-			if ( ! frequencyInput ) {
-				return;
-			}
-			if ( layout === 'tiered' ) {
-				const frequencyButton = document.querySelector( `button[data-frequency-slug="${ frequency }"]` );
-				if ( ! frequencyButton ) {
-					return;
-				}
-				frequencyButton.click();
-				const submitButton = donationForm.querySelector( `button[type="submit"][name="donation_value_${ frequency }"][value="${ amount }"]` );
-				if ( ! submitButton ) {
-					return;
-				}
-				submitButton.click();
-			} else {
-				const amountInput =
-					layout === 'untiered'
-						? donationForm.querySelector( `input[name="donation_value_${ frequency }_untiered"]` )
-						: donationForm.querySelector( `input[name="donation_value_${ frequency }"][value="${ amount }"]` );
-				if ( frequencyInput && amountInput ) {
-					frequencyInput.checked = true;
-					if ( layout === 'untiered' ) {
-						amountInput.value = amount;
-					} else if ( amount === 'other' ) {
-						amountInput.click();
-						const otherInput = donationForm.querySelector( `input[name="donation_value_${ frequency }_other"]` );
-						if ( otherInput && other ) {
-							otherInput.value = other;
-						}
-					} else {
-						amountInput.checked = true;
+		const resolution = resolveDonationTrigger( document, { layout, frequency, amount } );
+		const described = `layout "${ layout }", frequency "${ frequency }" and amount "${ amount }"`;
+		if ( resolution.status === 'invalid-params' ) {
+			// eslint-disable-next-line no-console
+			console.warn( `Newspack modal checkout: invalid donate trigger parameters (${ described }). The checkout was not triggered.` );
+			return false;
+		}
+		if ( resolution.status === 'no-match' ) {
+			// eslint-disable-next-line no-console
+			console.warn( `Newspack modal checkout: no donate form matches ${ described }. The checkout was not triggered.` );
+			return false;
+		}
+		if ( resolution.status === 'not-ready' ) {
+			// The tiersBased view script has not initialized this block yet —
+			// modal.js and tiersBased.js load async in either order, and when
+			// modal.js is first (typical on fast/cached loads, where execution
+			// follows document order and modal.js is printed first) tab and tier
+			// clicks would do nothing. Retry when the block announces readiness;
+			// the listener re-arms if the matching block still isn't the one that
+			// became ready. Returning false keeps the URL params (see
+			// handleModalCheckoutUrlParams), so the retry — or a reload, if
+			// readiness never comes — still has them; a successful retry strips
+			// them here since the caller's pass is already over. Waiting is the
+			// expected order on healthy loads, so nothing is logged unless
+			// readiness never arrives.
+			const readyWarningTimeout = setTimeout( () => {
+				// eslint-disable-next-line no-console
+				console.warn(
+					`Newspack modal checkout: the donate form matching ${ described } never finished initializing. The checkout was not triggered; the URL params were kept so a reload can retry.`
+				);
+			}, 5000 );
+			document.addEventListener(
+				TIERS_BASED_READY_EVENT,
+				() => {
+					clearTimeout( readyWarningTimeout );
+					if ( triggerDonationForm( layout, frequency, amount, other ) ) {
+						stripCheckoutUrlParams();
 					}
-					form = donationForm;
-				}
+				},
+				{ once: true }
+			);
+			return false;
+		}
+		const { form } = resolution;
+		if ( resolution.status === 'tiered' ) {
+			// Clicking the tab synchronously updates each tier submit button's
+			// `name` and `value` attributes (see src/blocks/donate/tiers-based/view.ts);
+			// resolution already verified the view script is initialized. Blocks
+			// with a single enabled frequency render no tabs and need no click.
+			if ( resolution.frequencyButton ) {
+				resolution.frequencyButton.click();
 			}
-		} );
-		if ( form ) {
-			triggerFormSubmit( form );
+			const submitButton = form.querySelector( `button[type="submit"][data-tier-index="${ resolution.tierIndex }"]` );
+			if ( ! submitButton ) {
+				// eslint-disable-next-line no-console
+				console.warn( `Newspack modal checkout: no tier submit button matches ${ described }. The checkout was not triggered.` );
+				return false;
+			}
+			submitButton.click();
+			return true;
+		}
+		resolution.frequencyInput.checked = true;
+		if ( resolution.status === 'untiered' ) {
+			resolution.amountInput.value = amount;
+		} else if ( amount === 'other' ) {
+			resolution.amountInput.click();
+			const otherInput = form.querySelector( `input[name="donation_value_${ frequency }_other"]` );
+			if ( otherInput && other ) {
+				otherInput.value = other;
+			}
+		} else {
+			resolution.amountInput.checked = true;
+		}
+		// requestSubmit runs the form's constraint validation (e.g. the untiered
+		// amount input's `min`), and a refused submit would otherwise still be
+		// reported as success — stripping the URL params of a link that did
+		// nothing. Check first so failures stay visible and retryable.
+		if ( ! form.checkValidity() ) {
+			// eslint-disable-next-line no-console
+			console.warn( `Newspack modal checkout: the donate form rejected the values for ${ described }. The checkout was not triggered.` );
+			return false;
 		}
+		triggerFormSubmit( form );
+		return true;
 	};
 
 	/**
@@ -839,9 +907,10 @@ domReady( () => {
 		if ( ! urlParams.has( 'checkout' ) ) {
 			return;
 		}
-		// Default to stripping the params after handling. The checkout button
-		// trigger overrides this so a link that matches no form stays visible
-		// and diagnosable rather than being silently dropped.
+		// Default to stripping the params after handling. The donate and
+		// checkout button triggers override this so a link that fails to
+		// trigger stays visible and diagnosable rather than being silently
+		// dropped, and a reload can retry a transient failure.
 		let shouldStripParams = true;
 		const type = urlParams.get( 'type' );
 		if ( type === 'donate' ) {
@@ -850,7 +919,11 @@ domReady( () => {
 			const amount = urlParams.get( 'amount' );
 			const other = urlParams.get( 'other' );
 			if ( layout && frequency && amount ) {
-				triggerDonationForm( layout, frequency, amount, other );
+				shouldStripParams = triggerDonationForm( layout, frequency, amount, other );
+			} else {
+				shouldStripParams = false;
+				// eslint-disable-next-line no-console
+				console.warn( 'Newspack modal checkout: donate trigger is missing layout, frequency or amount. The checkout was not triggered.' );
 			}
 		} else if ( type === 'checkout_button' ) {
 			const productId = urlParams.get( 'product_id' );
@@ -871,10 +944,10 @@ domReady( () => {
 				triggerFormSubmit( form );
 			}
 		}
-		// Remove the URL params to prevent re-triggering, but only when the
+		// Remove the trigger params to prevent re-triggering, but only when the
 		// trigger succeeded.
 		if ( shouldStripParams ) {
-			window.history.replaceState( null, null, window.location.pathname );
+			stripCheckoutUrlParams();
 		}
 	};
 	handleModalCheckoutUrlParams();
@@ -888,6 +961,7 @@ domReady( () => {
 	 * @param {string}   options.title              The title to set for the modal.
 	 * @param {string}   options.actionType         The action type to set for the modal.
 	 * @param {Object}   options.afterSuccess       The after success configuration object.
+	 * @param {number}   options.quantity           Optional. Seats/quantity to purchase. Only sent when above 1.
 	 * @param {Function} options.onCheckoutComplete The callback to call when the checkout is complete.
 	 * @param {Function} options.onClose            The callback to call when the modal is closed.
 	 */
@@ -896,6 +970,7 @@ domReady( () => {
 		title = null,
 		actionType = null,
 		afterSuccess = {},
+		quantity = null,
 		// eslint-disable-next-line @typescript-eslint/no-shadow
 		onCheckoutComplete = null,
 		onClose = null,
@@ -933,6 +1008,15 @@ domReady( () => {
 			url.searchParams.set( 'action_type', actionType );
 		}
 
+		/**
+		 * Seat/quantity configuration. Only sent above 1 — the server already
+		 * defaults to a single seat, so there's nothing to add to the URL when
+		 * the reader is buying just one.
+		 */
+		if ( quantity && parseInt( quantity, 10 ) > 1 ) {
+			url.searchParams.set( 'quantity', String( parseInt( quantity, 10 ) ) );
+		}
+
 		/**
 		 * After success parameters.
 		 */

package/src/modal-checkout/utils.test.js

@@ -0,0 +1,49 @@
+/**
+ * Tests for modal-checkout utils.
+ */
+
+import { getCheckoutData } from './utils';
+
+afterEach( () => {
+	document.body.innerHTML = '';
+} );
+
+/**
+ * Build a checkout-button-style form: a `quantity` hidden input (as view.php
+ * emits when a block's default seat count is above 1) plus a `data-checkout`
+ * attribute carrying the server-computed checkout data.
+ *
+ * @param {Object} checkoutData Object to JSON-encode into data-checkout.
+ * @return {HTMLFormElement} The form element.
+ */
+const formWithQuantityField = checkoutData => {
+	document.body.innerHTML = `<form data-checkout='${ JSON.stringify(
+		checkoutData
+	) }'><input type="hidden" name="quantity" value="3"><button type="submit">Buy</button></form>`;
+	return document.body.querySelector( 'form' );
+};
+
+describe( 'getCheckoutData()', () => {
+	it( 'carries the quantity from a hidden form field when data-checkout omits it', () => {
+		// Mirrors a product source: Checkout_Data::get_checkout_data() omits
+		// `quantity` entirely for a bare product, so the only value with a seat
+		// count to report is the DOM's own hidden `quantity` input.
+		const form = formWithQuantityField( { product_id: '42', amount: '10' } );
+
+		const data = getCheckoutData( form );
+
+		expect( data.quantity ).toBe( '3' );
+	} );
+
+	it( 'lets data-checkout win when it does carry a quantity (cart/order sources)', () => {
+		// Mirrors a cart or order source: Checkout_Data::get_checkout_data() sets
+		// a real `quantity` there, and the merge order in getCheckoutData() must
+		// keep letting that JSON value win over whatever the DOM field says —
+		// this test exists to pin that merge order, not to change it.
+		const form = formWithQuantityField( { product_id: '42', amount: '10', quantity: 5 } );
+
+		const data = getCheckoutData( form );
+
+		expect( data.quantity ).toBe( 5 );
+	} );
+} );