@financial-times/n-conversion-forms 40.0.2 → 41.0.0

package/.toolkitstate/ci.json

@@ -1,7 +1,7 @@
 {
   "branch": "",
   "repo": "n-conversion-forms",
-  "version": "851ad665946f79ea01a1d6152a42c7a2debb3ceb",
-  "tag": "v40.0.2",
-  "buildNumber": "15060"
+  "version": "2cb838a4fc4d3fd5c1911d80503a2d927ec71a27",
+  "tag": "v41.0.0",
+  "buildNumber": "15084"
 }

package/.toolkitstate/install.json

@@ -1,5 +1,5 @@
 {
   ".toolkitrc.yml": "XiiIocllEaT8xqKRCTpTbJ+yUyduDo5aEHARUQ3vJFfSe187Ci13PEs3bWL272GFJyNz2QgRQhdov2/+LFRKuw==",
-  "package.json": "Or39bD7+0aRIUCealkxIwU9bZKt+MC9MGSiMCbScS+oU3bCrLld+sy7mq9xS0mkAbUmWYG5FxdbWSAgYajF/nA==",
+  "package.json": "Q++D0RhTdwacN2+LL5eQZaV5Ck5QP637EEpW6f9Mu8Jk/PXaa11O1cCs+/TUvXxCrvDVSbepecfSkDoRv/oXzg==",
   ".circleci/config.yml": "eph42EF3EsL7jvhiiC7D7vG3vGBAGBFVC+Ncmy4Dj4rUNzK8Rls0/cr+bEF/ttMN3J6iSL1xtCXKIJVrtZ4OSQ=="
 }

package/README.md

@@ -57,8 +57,9 @@ import MyModule from 'n-conversion-forms/utils/my-module';
 - [Event Notifier](#event-notifier)
 - [Loader](#loader)
 - [Password](#password)
-- [Payment Term](#payment-term)
-- [Payment Type](#payment-type)
+- [Payment Term](#paymentTerm)
+- [Payment Type](#paymentType)
+- [Region Selector](#regionSelector)
 - [Salesforce](#salesforce)
 - [Submit](#submit)
 - [Tracking](#tracking)
@@ -262,6 +263,32 @@ PaymentType.PAYPAL;
 PaymentType.APPLEPAY;
 ```
 
+### RegionSelector
+
+The `RegionSelector` utility provides a form element for selecting regions (states, provinces, etc.) based on the selected country. It supports dynamic naming and labeling based on the provided options.
+
+> **Note**: Ensure that the `country`, `regionType`, and `fieldId` used here match what is used in the props for the `RegionSelector` component in `region-selector.jsx`.
+
+#### Usage
+
+```js
+// Using default options
+const regionSelector = new RegionSelector(document, { country: 'CAN' });
+
+// Using custom options
+const customRegionSelector = new RegionSelector(document, {
+	country: 'IND',
+	regionType: 'customRegionType',
+	fieldId: 'customFieldId',
+});
+
+// Example of util functions
+regionSelector.hide();
+regionSelector.show();
+regionSelector.disable();
+regionSelector.enable();
+```
+
 ### Salesforce
 
 Utility for converting salesforce country names to ISO country codes.

package/components/index.js

@@ -46,11 +46,10 @@ export { PaymentType } from './payment-type';
 export { Phone } from './phone';
 export { Position } from './position';
 export { ProgressIndicator } from './progress-indicator';
-export { Province } from './province';
+export { RegionSelector } from './region-selector';
 export { RegistrationConfirmation } from './registration-confirmation';
 export { Responsibility } from './responsibility';
 export { Section } from './section';
-export { State } from './state';
 export { Submit } from './submit';
 export { TrialBanner } from './trial-banner';
 export { EducationJobTitle } from './education-job-title';

package/components/region-selector.jsx

@@ -0,0 +1,99 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import classNames from 'classnames';
+
+import { configByCountry } from '../utils/region-selector';
+
+export function RegionSelector({
+	country = 'USA',
+	fieldId,
+	hasError = false,
+	isBillingSelector = false,
+	isDisabled = false,
+	isHidden = false,
+	label,
+	regionType,
+	selectId,
+	value,
+}) {
+	const {
+		regions = [],
+		defaultRegionType,
+		label: defaultLabel,
+	} = configByCountry[country];
+
+	const dynamicRegionType = regionType || defaultRegionType;
+	const dynamicLabel = isBillingSelector
+		? `Billing ${label || defaultLabel}`
+		: label || defaultLabel;
+	const dynamicFieldId = fieldId || `${dynamicRegionType}Field`;
+	const dynamicSelectId = selectId || dynamicRegionType;
+
+	const dynamicName = isBillingSelector
+		? `billing${
+				dynamicRegionType.charAt(0).toUpperCase() + dynamicRegionType.slice(1)
+			}`
+		: dynamicRegionType;
+
+	const fieldClassNames = classNames([
+		'o-forms-field',
+		{ ncf__hidden: isHidden },
+	]);
+
+	const inputWrapperClassNames = classNames([
+		'o-forms-input',
+		'o-forms-input--select',
+		{ 'o-forms-input--invalid': hasError },
+	]);
+
+	return (
+		<label
+			id={dynamicFieldId}
+			className={fieldClassNames}
+			data-validate="required"
+			htmlFor={dynamicSelectId}
+		>
+			<span className="o-forms-title">
+				<span className="o-forms-title__main">{dynamicLabel}</span>
+			</span>
+			<span className={inputWrapperClassNames}>
+				<select
+					id={selectId}
+					aria-required="true"
+					required
+					name={dynamicName}
+					data-trackable={`field-${dynamicRegionType}`}
+					disabled={isDisabled}
+					defaultValue={value}
+				>
+					<option disabled value="">
+						Please select a {defaultLabel.toLowerCase()}
+					</option>
+					{regions.map(({ code, name }) => {
+						return (
+							<option key={code} value={code}>
+								{name}
+							</option>
+						);
+					})}
+				</select>
+				<span className="o-forms-input__error">
+					Please select your {defaultLabel.toLowerCase()}
+				</span>
+			</span>
+		</label>
+	);
+}
+
+RegionSelector.propTypes = {
+	country: PropTypes.oneOf(['USA', 'CAN', 'IND']),
+	fieldId: PropTypes.string,
+	hasError: PropTypes.bool,
+	isBillingSelector: PropTypes.bool,
+	isDisabled: PropTypes.bool,
+	isHidden: PropTypes.bool,
+	label: PropTypes.string,
+	regionType: PropTypes.string,
+	selectId: PropTypes.string,
+	value: PropTypes.string,
+};

package/components/region-selector.spec.js

@@ -0,0 +1,121 @@
+import React from 'react';
+import { RegionSelector } from './region-selector';
+import Enzyme, { mount } from 'enzyme';
+import Adapter from 'enzyme-adapter-react-16';
+Enzyme.configure({ adapter: new Adapter() });
+
+describe('RegionSelector', () => {
+	it('renders a select with a label', () => {
+		const props = {
+			country: 'USA',
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('label').exists()).toBe(true);
+		expect(component.find('select').exists()).toBe(true);
+	});
+
+	it('renders the correct label based on country and isBillingSelector', () => {
+		const props = {
+			country: 'CAN',
+			isBillingSelector: true,
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('label').text()).toContain('Billing Province');
+	});
+
+	it('can render an initial selected value', () => {
+		const props = {
+			country: 'USA',
+			value: 'AR',
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('select').prop('defaultValue')).toBe('AR');
+	});
+
+	it('can render a disabled select', () => {
+		const props = {
+			country: 'USA',
+			isDisabled: true,
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('select').prop('disabled')).toBe(true);
+	});
+
+	it('can render an error state', () => {
+		const props = {
+			country: 'USA',
+			hasError: true,
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('.o-forms-input--invalid').exists()).toBe(true);
+	});
+
+	it('can hide the component', () => {
+		const props = {
+			country: 'USA',
+			isHidden: true,
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('.ncf__hidden').exists()).toBe(true);
+	});
+
+	it('can override id for field', () => {
+		const props = {
+			country: 'USA',
+			fieldId: 'customFieldId',
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('#customFieldId').exists()).toBe(true);
+	});
+
+	it('can override id for select', () => {
+		const props = {
+			country: 'USA',
+			selectId: 'customSelectId',
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('select#customSelectId').exists()).toBe(true);
+	});
+
+	it('applies context-specific name if is billing state', () => {
+		const props = {
+			country: 'USA',
+			isBillingSelector: true,
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('select').prop('name')).toBe('billingState');
+	});
+
+	it('applies context-specific name if is not billing state', () => {
+		const props = {
+			country: 'USA',
+			isBillingSelector: false,
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('select').prop('name')).toBe('state');
+	});
+
+	it('renders the correct label for USA', () => {
+		const props = {
+			country: 'USA',
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('label').text()).toContain('State');
+	});
+
+	it('renders the correct label for CAN', () => {
+		const props = {
+			country: 'CAN',
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('label').text()).toContain('Province');
+	});
+
+	it('renders the correct label for IND', () => {
+		const props = {
+			country: 'IND',
+		};
+		const component = mount(<RegionSelector {...props} />);
+		expect(component.find('label').text()).toContain('State/Union Territory');
+	});
+});

package/components/region-selector.stories.js

@@ -0,0 +1,84 @@
+import React from 'react';
+import { RegionSelector } from './region-selector';
+
+export default {
+	title: 'Region Selector',
+	component: RegionSelector,
+	argTypes: {
+		country: { control: 'radio', options: ['USA', 'CAN', 'IND'] },
+		hasError: { control: 'boolean' },
+		isHidden: { control: 'boolean' },
+		isBillingSelector: { control: 'boolean' },
+		isDisabled: { control: 'boolean' },
+		region: { control: 'text' },
+		fieldId: { control: 'text' },
+		selectId: { control: 'text' },
+		label: { control: 'text' },
+		value: { control: 'text' },
+	},
+	parameters: {
+		docs: {
+			description: {
+				component: `
+The \`RegionSelector\` component is used to select regions (states, provinces, etc.) based on the selected country. It supports dynamic naming and labeling based on the provided props.
+
+### Props
+- **country**: The country code (e.g., 'USA', 'CAN', 'IND') to determine the list of regions.
+- **value**: The selected value for the region.
+- **fieldId**: Custom ID for the field label. If not provided, it defaults to \`\${region}Field\`.
+- **selectId**: Custom ID for the select element. If not provided, it defaults to \`region\`.
+- **label**: Custom label for the field. If not provided, it defaults to the region label based on the country.
+- **hasError**: Boolean to indicate if the field has an error.
+- **isHidden**: Boolean to indicate if the field should be hidden.
+- **isBillingState**: Boolean to indicate if the field is for billing purposes. Adds 'Billing' prefix to the label.
+- **isDisabled**: Boolean to indicate if the field should be disabled.
+- **region**: Custom region name (e.g., 'state', 'province'). If not provided, it defaults to the country's default region.
+
+### Dynamic Logic
+- **Dynamic Label**: The label is constructed based on the \`label\` prop, the country's default label, and whether it is a billing field.
+- **Dynamic IDs and Names**: The \`fieldId\`, \`selectId\`, and \`name\` attributes are dynamically generated based on the \`region\` prop or the country's default region. If \`fieldId\` and \`selectId\` are provided, they are used directly.
+
+						`,
+			},
+		},
+	},
+};
+
+export const Basic = (args) => <RegionSelector {...args} />;
+Basic.args = {
+	country: 'USA',
+	value: '',
+	hasError: false,
+	isHidden: false,
+	isBillingSelector: false,
+	isDisabled: false,
+	region: '',
+	fieldId: '',
+	selectId: '',
+	label: '',
+};
+
+export const BillingState = Basic.bind({});
+BillingState.args = {
+	...Basic.args,
+	isBillingSelector: true,
+};
+
+export const CustomRegion = Basic.bind({});
+CustomRegion.args = {
+	...Basic.args,
+	region: 'province',
+};
+
+export const CustomFieldIdAndSelectId = Basic.bind({});
+CustomFieldIdAndSelectId.args = {
+	...Basic.args,
+	fieldId: 'customFieldId',
+	selectId: 'customSelectId',
+};
+
+export const CustomLabel = Basic.bind({});
+CustomLabel.args = {
+	...Basic.args,
+	label: 'Custom Label',
+};

package/dist/index.js

@@ -315,10 +315,10 @@ Object.defineProperty(exports, "ProgressIndicator", {
     return _progressIndicator.ProgressIndicator;
   }
 });
-Object.defineProperty(exports, "Province", {
+Object.defineProperty(exports, "RegionSelector", {
   enumerable: true,
   get: function get() {
-    return _province.Province;
+    return _regionSelector.RegionSelector;
   }
 });
 Object.defineProperty(exports, "RegistrationConfirmation", {
@@ -339,12 +339,6 @@ Object.defineProperty(exports, "Section", {
     return _section.Section;
   }
 });
-Object.defineProperty(exports, "State", {
-  enumerable: true,
-  get: function get() {
-    return _state.State;
-  }
-});
 Object.defineProperty(exports, "Submit", {
   enumerable: true,
   get: function get() {
@@ -411,11 +405,10 @@ var _paymentType = require("./payment-type");
 var _phone = require("./phone");
 var _position = require("./position");
 var _progressIndicator = require("./progress-indicator");
-var _province = require("./province");
+var _regionSelector = require("./region-selector");
 var _registrationConfirmation = require("./registration-confirmation");
 var _responsibility = require("./responsibility");
 var _section = require("./section");
-var _state = require("./state");
 var _submit = require("./submit");
 var _trialBanner = require("./trial-banner");
 var _educationJobTitle = require("./education-job-title");

package/dist/{province.jsx → region-selector.jsx}

@@ -4,28 +4,37 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.Province = Province;
+exports.RegionSelector = RegionSelector;
 var _react = _interopRequireDefault(require("react"));
 var _propTypes = _interopRequireDefault(require("prop-types"));
 var _classnames = _interopRequireDefault(require("classnames"));
-var _nCommonStaticData = require("n-common-static-data");
-var defaultProvinces = _nCommonStaticData.canadianProvinces.provinces;
-function Province(_ref) {
-  var value = _ref.value,
-    _ref$fieldId = _ref.fieldId,
-    fieldId = _ref$fieldId === void 0 ? 'provinceField' : _ref$fieldId,
-    _ref$selectId = _ref.selectId,
-    selectId = _ref$selectId === void 0 ? 'province' : _ref$selectId,
+var _regionSelector = require("../utils/region-selector");
+function RegionSelector(_ref) {
+  var _ref$country = _ref.country,
+    country = _ref$country === void 0 ? 'USA' : _ref$country,
+    fieldId = _ref.fieldId,
     _ref$hasError = _ref.hasError,
     hasError = _ref$hasError === void 0 ? false : _ref$hasError,
-    _ref$isHidden = _ref.isHidden,
-    isHidden = _ref$isHidden === void 0 ? false : _ref$isHidden,
-    _ref$isBillingProvinc = _ref.isBillingProvince,
-    isBillingProvince = _ref$isBillingProvinc === void 0 ? false : _ref$isBillingProvinc,
+    _ref$isBillingSelecto = _ref.isBillingSelector,
+    isBillingSelector = _ref$isBillingSelecto === void 0 ? false : _ref$isBillingSelecto,
     _ref$isDisabled = _ref.isDisabled,
     isDisabled = _ref$isDisabled === void 0 ? false : _ref$isDisabled,
-    _ref$provinces = _ref.provinces,
-    provinces = _ref$provinces === void 0 ? defaultProvinces : _ref$provinces;
+    _ref$isHidden = _ref.isHidden,
+    isHidden = _ref$isHidden === void 0 ? false : _ref$isHidden,
+    label = _ref.label,
+    regionType = _ref.regionType,
+    selectId = _ref.selectId,
+    value = _ref.value;
+  var _configByCountry$coun = _regionSelector.configByCountry[country],
+    _configByCountry$coun2 = _configByCountry$coun.regions,
+    regions = _configByCountry$coun2 === void 0 ? [] : _configByCountry$coun2,
+    defaultRegionType = _configByCountry$coun.defaultRegionType,
+    defaultLabel = _configByCountry$coun.label;
+  var dynamicRegionType = regionType || defaultRegionType;
+  var dynamicLabel = isBillingSelector ? "Billing ".concat(label || defaultLabel) : label || defaultLabel;
+  var dynamicFieldId = fieldId || "".concat(dynamicRegionType, "Field");
+  var dynamicSelectId = selectId || dynamicRegionType;
+  var dynamicName = isBillingSelector ? "billing".concat(dynamicRegionType.charAt(0).toUpperCase() + dynamicRegionType.slice(1)) : dynamicRegionType;
   var fieldClassNames = (0, _classnames["default"])(['o-forms-field', {
     ncf__hidden: isHidden
   }]);
@@ -33,28 +42,28 @@ function Province(_ref) {
     'o-forms-input--invalid': hasError
   }]);
   return /*#__PURE__*/_react["default"].createElement("label", {
-    id: fieldId,
+    id: dynamicFieldId,
     className: fieldClassNames,
     "data-validate": "required",
-    htmlFor: selectId
+    htmlFor: dynamicSelectId
   }, /*#__PURE__*/_react["default"].createElement("span", {
     className: "o-forms-title"
   }, /*#__PURE__*/_react["default"].createElement("span", {
     className: "o-forms-title__main"
-  }, isBillingProvince ? 'Billing ' : '', "Province")), /*#__PURE__*/_react["default"].createElement("span", {
+  }, dynamicLabel)), /*#__PURE__*/_react["default"].createElement("span", {
     className: inputWrapperClassNames
   }, /*#__PURE__*/_react["default"].createElement("select", {
     id: selectId,
     "aria-required": "true",
     required: true,
-    name: isBillingProvince ? 'billingProvince' : 'province',
-    "data-trackable": "field-province",
+    name: dynamicName,
+    "data-trackable": "field-".concat(dynamicRegionType),
     disabled: isDisabled,
     defaultValue: value
   }, /*#__PURE__*/_react["default"].createElement("option", {
     disabled: true,
     value: ""
-  }, "Please select a province"), provinces.map(function (_ref2) {
+  }, "Please select a ", defaultLabel.toLowerCase()), regions.map(function (_ref2) {
     var code = _ref2.code,
       name = _ref2.name;
     return /*#__PURE__*/_react["default"].createElement("option", {
@@ -63,18 +72,17 @@ function Province(_ref) {
     }, name);
   })), /*#__PURE__*/_react["default"].createElement("span", {
     className: "o-forms-input__error"
-  }, "Please select your province.")));
+  }, "Please select your ", defaultLabel.toLowerCase())));
 }
-Province.propTypes = {
-  value: _propTypes["default"].string,
+RegionSelector.propTypes = {
+  country: _propTypes["default"].oneOf(['USA', 'CAN', 'IND']),
   fieldId: _propTypes["default"].string,
-  selectId: _propTypes["default"].string,
   hasError: _propTypes["default"].bool,
-  isHidden: _propTypes["default"].bool,
-  isBillingProvince: _propTypes["default"].bool,
+  isBillingSelector: _propTypes["default"].bool,
   isDisabled: _propTypes["default"].bool,
-  provinces: _propTypes["default"].arrayOf(_propTypes["default"].shape({
-    code: _propTypes["default"].string,
-    name: _propTypes["default"].string
-  }))
+  isHidden: _propTypes["default"].bool,
+  label: _propTypes["default"].string,
+  regionType: _propTypes["default"].string,
+  selectId: _propTypes["default"].string,
+  value: _propTypes["default"].string
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@financial-times/n-conversion-forms",
-  "version": "40.0.2",
+  "version": "41.0.0",
   "description": "Containing jsx components and styles for forms included on Accounts and Acquisition apps (next-signup, next-profile, next-retention, etc).",
   "main": "./dist/index.js",
   "scripts": {
@@ -30,7 +30,7 @@
     "classnames": "2.5.1",
     "fetchres": "1.7.2",
     "lodash.get": "4.4.2",
-    "n-common-static-data": "github:Financial-Times/n-common-static-data#v3.0.0"
+    "n-common-static-data": "github:Financial-Times/n-common-static-data#v3.1.0"
   },
   "devDependencies": {
     "@babel/core": "^7.23.9",

package/utils/region-selector.js

@@ -0,0 +1,54 @@
+import {
+	americanStates,
+	canadianProvinces,
+	indianStatesAndUnionTerritories,
+} from 'n-common-static-data';
+import FormElement from './form-element';
+
+export const configByCountry = {
+	USA: {
+		regions: americanStates.states,
+		defaultRegionType: 'state',
+		label: 'State',
+	},
+	CAN: {
+		regions: canadianProvinces.provinces,
+		defaultRegionType: 'province',
+		label: 'Province',
+	},
+	IND: {
+		regions: indianStatesAndUnionTerritories.states,
+		defaultRegionType: 'state',
+		label: 'State/Union Territory',
+	},
+};
+
+/**
+ * Class representing a region selector form element.
+ * @extends FormElement
+ */
+class RegionSelector extends FormElement {
+	/**
+	 * Create a region selector.
+	 *
+	 * @param {Document} document - The document object.
+	 * @param {Object} [options] - Options for the region selector.
+	 * @param {string} [options.country='USA'] - The country code (e.g., 'USA', 'CAN', 'IND'). Defaults to 'USA'.
+	 * @param {string} [options.regionType] - The type of region (e.g., 'state', 'province'). Defaults to the default region type for the country.
+	 * @param {string} [options.fieldId] - The ID of the field element. Defaults to the default field ID for the region type.
+	 *
+	 * @note Ensure that the `country`, `regionType` and `fieldId` used here matches what is used in the props for the `RegionSelector` component.
+	 */
+	constructor(document, { country = 'USA', regionType, fieldId } = {}) {
+		const defaultRegionType =
+			regionType || configByCountry[country].defaultRegionType;
+
+		const selector = fieldId
+			? `.ncf #${fieldId}`
+			: `.ncf #${defaultRegionType}Field`;
+
+		super(document, selector);
+	}
+}
+
+export default RegionSelector;