@financial-times/n-conversion-forms 46.0.1 → 47.0.1

package/components/delivery-option.stories.js

@@ -34,12 +34,12 @@ Basic.args = {
 	],
 };
 
-export const UKPaperVoucherAutoReniewingDeliveryOptions = (args) => (
+export const UKPaperVoucherAutoRenewingDeliveryOptions = (args) => (
 	<div className="ncf">
 		<DeliveryOption {...args} />
 	</div>
 );
-UKPaperVoucherAutoReniewingDeliveryOptions.args = {
+UKPaperVoucherAutoRenewingDeliveryOptions.args = {
 	country: 'GBR',
 	options: [
 		{

package/components/payment-term.jsx

@@ -1,7 +1,9 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import classNames from 'classnames';
-import { Period, Monthly } from '@financial-times/n-pricing';
+import { Period, Price } from '@financial-times/n-pricing';
+
+import { getDurationFromISO8601Value, is52WeeksOrLonger } from '../helpers';
 
 export function PaymentTerm({
 	fieldId = 'paymentTermField',
@@ -17,159 +19,40 @@ export function PaymentTerm({
 	isNonRenewingSubscriptionTermType = false,
 }) {
 	/**
-	 * Compute monthly price for given term name
-	 * @param {number} amount price in number format
-	 * @param {string} currency country id of the currency
-	 * @param {string} period (expressed in IS0 8601 duration format): e.g. PxY (yearly) or PxM (montly) where x is the amount of years/months
+	 * Capitalises a string.
+	 * @param {string} Input string to be capitalised
 	 * @returns {string}
 	 */
-	const getMonthlyPriceFromPeriod = (amount, currency, period) => {
-		const periodObj = new Period(period);
-		const monthlyPrice = periodObj.calculatePrice('P1M', amount);
-		return new Monthly({ value: monthlyPrice, currency }).getAmount('monthly');
-	};
+	const capitalise = (string) =>
+		Boolean(string) ? string[0].toUpperCase() + string.slice(1) : string;
 
 	/**
-	 * returns period converted to time if found
-	 * otherwise returns empty string to avoid show information not mapped
-	 * @param {string} period (expressed in IS0 8601 duration format): PxY (yearly), PxM (montly), PxW (weekly), of PxD (daily), where x is the amount of years/months/weeks/days
-	 * @returns {string}
+	 * Creates the JSX for a single payment-term option, including the input,
+	 * title, discount messaging, and descriptive pricing copy.
+	 *
+	 * @param {Object} option - Payment term configuration
+	 * @param {string} option.value - ISO 8601 duration of the subscription term of the offer
+	 * @param {string} option.name - term name, e.g. "monthly", "annual", "2 yearly
+	 * @param {string} option.price - Formatted display price
+	 * @param {string|number} [option.amount] - Price expressed in numerical terms
+	 * @param {string} [option.symbol] - Currency symbol, e.g. £
+	 * @param {string} [option.monthlyPrice] - Precomputed monthly equivalent price (can be with or without currency symbol)
+	 * @param {boolean} [option.discount] - Whether the option should display discount messaging
+	 * @param {boolean} [option.bestOffer] - Whether the option should show "Best offer" instead of standard discount copy
+	 * @param {boolean} [option.selected] - Whether the option is selected by default
+	 * @param {boolean} [option.isTrial] - Whether the option is a trial offer
+	 * @param {boolean} [option.subscriptionAutoRenewTerm] - Whether the option is for an auto-renewing subscription
+	 * @param {number} [option.trialAmount] - Amount used for trial pricing
+	 * @param {string} [option.trialDuration] - Human-readable trial duration copy
+	 * @param {string} [option.trialPrice] - Formatted trial price
+	 * @param {string} [option.displayName] - Override label for the term title
+	 * @param {string} [option.title] - Fallback title for legacy or non-period terms
+	 * @param {string} [option.subTitle] - Optional subtitle shown alongside the term title
+	 * @param {string} [option.chargeOnText] - Optional charge timing copy for non-period offers
+	 * @param {boolean} [option.b2cPartnership] - Whether the option is part of a B2C partnership offer
+	 * @param {string} [option.b2cDiscountCopy] - Partnership-specific discount copy
+	 * @returns {React.ReactElement} A rendered payment term option
 	 */
-	const getTimeFromPeriod = (period) => {
-		const periodUnitCodeToWordMap = {
-			Y: 'years',
-			M: 'months',
-			W: 'weeks',
-			D: 'days',
-		};
-
-		const periodUnitCode = period.substring(period.length - 1);
-
-		const freq = periodUnitCodeToWordMap[periodUnitCode] || '';
-
-		const amount = period.substring(1, period.length - 1);
-
-		return period ? `${amount} ${freq}` : '';
-	};
-
-	const isValidPeriod = (period) => {
-		try {
-			// Period should throw an error if it is not properly provided
-			// in order to validate it, we just send in case type is string
-			new Period(typeof period === 'string' ? period : '');
-			return true;
-		} catch (e) {
-			return false;
-		}
-	};
-
-	const nameMap = {
-		annual: {
-			title: 'Annual',
-			price: (price) => (
-				<React.Fragment>
-					Single{' '}
-					<span className="ncf__payment-term__price ncf__strong">{price}</span>{' '}
-					payment
-				</React.Fragment>
-			),
-			trialPrice: (price) => (
-				<React.Fragment>
-					Unless you cancel during your trial you will be billed{' '}
-					<span className="ncf__payment-term__price">{price}</span> per year
-					after the trial period.
-				</React.Fragment>
-			),
-			monthlyPrice: (price) =>
-				price && (
-					<span className="ncf__payment-term__equivalent-price">
-						That’s equivalent to{' '}
-						<span className="ncf__payment-term__monthly-price">{price}</span>{' '}
-						per month
-					</span>
-				),
-			renewsText: () => (
-				<p className="ncf__payment-term__renews-text">
-					Renews annually unless cancelled
-				</p>
-			),
-		},
-		quarterly: {
-			title: 'Quarterly',
-			price: (price) => (
-				<React.Fragment>
-					<span className="ncf__payment-term__price">{price}</span> per quarter
-				</React.Fragment>
-			),
-			trialPrice: (price) => (
-				<React.Fragment>
-					Unless you cancel during your trial you will be billed{' '}
-					<span className="ncf__payment-term__price">{price}</span> per quarter
-					after the trial period.
-				</React.Fragment>
-			),
-			monthlyPrice: () => {},
-			renewsText: () => (
-				<p className="ncf__payment-term__renews-text">
-					Renews quarterly unless cancelled
-				</p>
-			),
-		},
-		monthly: {
-			title: 'Monthly',
-			price: (price) => (
-				<React.Fragment>
-					<span className="ncf__payment-term__price">{price}</span> per month
-				</React.Fragment>
-			),
-			trialPrice: (price) => (
-				<React.Fragment>
-					Unless you cancel during your trial you will be billed{' '}
-					<span className="ncf__payment-term__price">{price}</span> per month
-					after the trial period.
-				</React.Fragment>
-			),
-			monthlyPrice: () => {},
-			renewsText: () => (
-				<p className="ncf__payment-term__renews-text">
-					{'Renews monthly unless cancelled'}
-				</p>
-			),
-		},
-		custom: {
-			price: (price) => (
-				<React.Fragment>
-					Single{' '}
-					<span className="ncf__payment-term__price ncf__strong">{price}</span>{' '}
-					payment
-				</React.Fragment>
-			),
-			trialPrice: (trialPrice, trialPeriod) => (
-				<React.Fragment>
-					Unless you cancel during your trial you will be billed{' '}
-					<span className="ncf__payment-term__price">{trialPrice}</span> per{' '}
-					{trialPeriod}
-					after the trial period.
-				</React.Fragment>
-			),
-			monthlyPrice: (monthlyPrice) =>
-				Boolean(monthlyPrice) && (
-					<span className="ncf__payment-term__equivalent-price">
-						That’s equivalent to{' '}
-						<span className="ncf__payment-term__monthly-price">
-							{monthlyPrice}
-						</span>{' '}
-						per month
-					</span>
-				),
-			renewsText: (renewalPeriod) =>
-				Boolean(renewalPeriod) && (
-					<p className="ncf__payment-term__renews-text">
-						Renews every {renewalPeriod} unless cancelled
-					</p>
-				),
-		},
-	};
 	const createPaymentTerm = (option) => {
 		const className = classNames([
 			'ncf__payment-term__item',
@@ -187,6 +70,161 @@ export function PaymentTerm({
 			...(option.selected && { defaultChecked: true }),
 		};
 
+		/**
+		 * Determines whether input is a valid ISO 8601 duration value that can be decoded by the Period class.
+		 * @returns {boolean}
+		 */
+		const isValidPeriod = () => {
+			try {
+				// Period should throw an error if it is not properly provided
+				// in order to validate it, we just send in case type is string
+				new Period(typeof option.value === 'string' ? option.value : '');
+				return true;
+			} catch (error) {
+				return false;
+			}
+		};
+
+		/**
+		 * Compute monthly price for given term name, if the term if 90 days or longer.
+		 * @returns {string | undefined}
+		 */
+		const getCalculatedMonthlyPriceIfEligible = () => {
+			const priceObject = new Price(
+				{
+					value: option.amount,
+					symbol: option.symbol,
+				},
+				{
+					period: option.value,
+				}
+			);
+			return priceObject.getMonthlyEquivalentIf90DaysOrLonger()?.amount.value;
+		};
+
+		/**
+		 * Returns elements that include the text describing the price of the offer option.
+		 * @returns {React.ReactElement}
+		 */
+		const getPriceText = () => {
+			const isExpressedAsSinglePayment =
+				!option.subscriptionAutoRenewTerm ||
+				// With an auto-renewing annual term there is a high chance
+				// it will not be the same price in the second year,
+				// so we do not want to imply that the price will remain consistent.
+				// For shorter auto-renewing terms there is higher confidence that the price
+				// will remain consistent across subsequent terms.
+				(option.subscriptionAutoRenewTerm && is52WeeksOrLonger(option.value));
+
+			const isExpressedAsRecurringPayment = !isExpressedAsSinglePayment;
+
+			if (isExpressedAsSinglePayment) {
+				return (
+					<React.Fragment>
+						Single{' '}
+						<span className="ncf__payment-term__price">{option.price}</span>{' '}
+						payment
+					</React.Fragment>
+				);
+			}
+
+			if (isExpressedAsRecurringPayment) {
+				return (
+					<React.Fragment>
+						<span className="ncf__payment-term__price">{option.price}</span> per{' '}
+						{getDurationFromISO8601Value({
+							iso8601Value: option.value,
+						})}
+					</React.Fragment>
+				);
+			}
+		};
+
+		/**
+		 * Returns elements that include the text describing the price increase following the trial period.
+		 * @returns {React.ReactElement}
+		 */
+		const getTrialPriceExplanatoryText = () => {
+			return (
+				<React.Fragment>
+					Unless you cancel during your trial you will be billed{' '}
+					<span className="ncf__payment-term__price">{option.price}</span> per{' '}
+					{getDurationFromISO8601Value({
+						iso8601Value: option.value,
+					})}{' '}
+					after the trial period.
+				</React.Fragment>
+			);
+		};
+
+		/**
+		 * Returns elements that include the text describing how regularly an auto-renewing subscription will renew.
+		 * @returns {React.ReactElement}
+		 */
+		const getRenewalPeriodText = () => {
+			return (
+				<p className="ncf__payment-term__renews-text">
+					Renews every{' '}
+					{getDurationFromISO8601Value({ iso8601Value: option.value })} unless
+					cancelled
+				</p>
+			);
+		};
+
+		/**
+		 * Returns elements that include the text describing the monthly equivalent of the subscription.
+		 * Returns null if the term is shorter than 90 days
+		 * @returns {string | null}
+		 */
+		const getEquivalentMonthlyPrice = () => {
+			const calculatedMonthlyPrice = getCalculatedMonthlyPriceIfEligible();
+
+			if (!calculatedMonthlyPrice) {
+				return null;
+			}
+
+			const hasValidMonthlyPrice =
+				option.monthlyPrice !== null &&
+				option.monthlyPrice !== undefined &&
+				option.monthlyPrice !== '' &&
+				option.monthlyPrice !== '0';
+
+			if (hasValidMonthlyPrice) {
+				return isNaN(option.monthlyPrice)
+					? option.monthlyPrice
+					: `${option.symbol}${option.monthlyPrice}`;
+			}
+
+			return calculatedMonthlyPrice;
+		};
+
+		/**
+		 * Returns elements that include the text describing the monthly equivalent of the subscription, if available.
+		 * @returns {React.ReactElement | null}
+		 */
+		const getEquivalentMonthlyPriceText = () => {
+			const equivalentMonthlyPrice = getEquivalentMonthlyPrice();
+
+			if (!equivalentMonthlyPrice) {
+				return null;
+			}
+			return (
+				<span className="ncf__payment-term__equivalent-price">
+					That’s equivalent to{' '}
+					<span className="ncf__payment-term__monthly-price">
+						{equivalentMonthlyPrice}
+					</span>{' '}
+					per month
+				</span>
+			);
+		};
+
+		/**
+		 * Creates the standard discount badge for an option.
+		 * Displays either "Best offer" or "Save X off RRP" when a discount exists.
+		 *
+		 * @returns {React.ReactElement} The discount element, or false when no discount should be shown
+		 */
 		const createDiscount = () => {
 			return (
 				option.discount && (
@@ -199,6 +237,11 @@ export function PaymentTerm({
 			);
 		};
 
+		/**
+		 * Creates B2C partnership discount copy for eligible annual offers.
+		 *
+		 * @returns {React.ReactElement} The B2C discount element, or false when the option is not eligible
+		 */
 		const createB2cDiscountCopy = () => {
 			return (
 				option.name === 'annual' &&
@@ -211,70 +254,63 @@ export function PaymentTerm({
 			);
 		};
 
+		/**
+		 * Creates the description shown beneath the term title.
+		 * This may include trial copy, price-per-period copy, equivalent monthly price,
+		 * renewal messaging, or fallback non-period pricing text.
+		 *
+		 * @returns {React.ReactElement} The description block for the payment term
+		 */
 		const createDescription = () => {
-			return option.isTrial ? (
-				<div className="ncf__payment-term__description">
-					{option.trialDuration || '4 weeks'} for{' '}
-					<span className="ncf__payment-term__trial-price">
-						{option.trialPrice}
+			if (option.isTrial) {
+				return (
+					<div className="ncf__payment-term__description">
+						{option.trialDuration || '4 weeks'} for{' '}
+						<span className="ncf__payment-term__trial-price">
+							{option.trialPrice}
+						</span>
+						<br />
+						{getTrialPriceExplanatoryText()}
+					</div>
+				);
+			}
+
+			if (isValidPeriod(option.value)) {
+				return (
+					<div className="ncf__payment-term__description">
+						{getPriceText()}
+						{getEquivalentMonthlyPriceText()}
+						{option.subscriptionAutoRenewTerm && getRenewalPeriodText()}
+					</div>
+				);
+			}
+
+			return (
+				<div>
+					<span className={largePrice ? 'ncf__payment-term__large-price' : ''}>
+						{option.price}
 					</span>
-					<br />
-					{nameMap[option.name] &&
-						nameMap[option.name].trialPrice(option.price)}
-				</div>
-			) : (
-				<React.Fragment>
-					{nameMap[option.name] ? (
-						<div className="ncf__payment-term__description">
-							{nameMap[option.name].price(option.price)}
-							{nameMap[option.name].monthlyPrice(option.monthlyPrice)}
-							{isAutoRenewingSubscriptionTermType &&
-								nameMap[option.name].renewsText()}
-							{/* Remove this discount text temporarily in favour of monthly price */}
-							{/* <br />Save up to 25% when you pay annually */}
-						</div>
-					) : // this should cover the cases different than annual, quarterly and monthly
-					// for those containing period on option.value, render custom template, for the rest keep legacy render
-					isValidPeriod(option.value) ? (
-						<div className="ncf__payment-term__description">
-							{nameMap['custom'].price(option.price)}
-							{nameMap['custom'].monthlyPrice(
-								option.monthlyPrice && option.monthlyPrice !== '0'
-									? Number(option.monthlyPrice)
-									: getMonthlyPriceFromPeriod(
-											option.amount,
-											option.currency,
-											option.value
-										)
-							)}
-							{isAutoRenewingSubscriptionTermType &&
-								nameMap['custom'].renewsText(getTimeFromPeriod(option.value))}
-						</div>
-					) : (
-						<div>
-							<span
-								className={largePrice ? 'ncf__payment-term__large-price' : ''}
-							>
-								{option.price}
-							</span>
-							{option.chargeOnText && (
-								<p className="ncf__payment-term__charge-on-text">
-									{option.chargeOnText}
-								</p>
-							)}
-						</div>
+					{option.chargeOnText && (
+						<p className="ncf__payment-term__charge-on-text">
+							{option.chargeOnText}
+						</p>
 					)}
-				</React.Fragment>
+				</div>
 			);
 		};
 
+		/**
+		 * Builds the display name shown as the payment term title.
+		 * May prepend trial copy, use the capitalised term name for auto-renewing terms,
+		 * derive a human-readable period for valid non-renewing terms, or fall back to
+		 * a legacy title when no valid period is available.
+		 *
+		 * @returns {string} The formatted display name for the payment term
+		 */
 		const getTermDisplayName = () => {
 			const showTrialCopyInTitle =
 				option.isTrial && !isPrintOrBundle && !isDigitalEdition;
 
-			const title =
-				option.name && nameMap[option.name] ? nameMap[option.name].title : '';
-
 			let termDisplayName = '';
 			if (showTrialCopyInTitle) {
 				const termName = option.displayName
@@ -284,13 +320,16 @@ export function PaymentTerm({
 			}
 
 			const getTermPeriod = () => {
-				// annual, quarterly and monthly
-				if (nameMap[option.name]) {
-					return title;
+				if (option.subscriptionAutoRenewTerm && option.name) {
+					return capitalise(option.name);
 				}
+
 				// custom offer with period provided
-				if (isValidPeriod(option.value)) {
-					return getTimeFromPeriod(option.value);
+				if (!option.subscriptionAutoRenewTerm && isValidPeriod(option.value)) {
+					return getDurationFromISO8601Value({
+						iso8601Value: option.value,
+						excludeAmountWhenSingular: false,
+					});
 				}
 				// custom legacy cases, where period is not provided
 				return option.title;
@@ -399,12 +438,14 @@ PaymentTerm.propTypes = {
 			isB2cPartnership: PropTypes.bool,
 			discount: PropTypes.string,
 			isTrial: PropTypes.bool,
+			subscriptionAutoRenewTerm: PropTypes.bool,
 			name: PropTypes.string.isRequired,
 			price: PropTypes.string.isRequired,
 			selected: PropTypes.bool,
 			trialDuration: PropTypes.string,
 			trialPrice: PropTypes.string,
 			amount: PropTypes.string,
+			symbol: PropTypes.string,
 			trialAmount: PropTypes.number,
 			value: PropTypes.string.isRequired,
 			monthlyPrice: PropTypes.string,