@hashicorp/react-components 0.0.0 → 1.0.0

package/src/components/marketo-form/fixtures/index.ts

@@ -0,0 +1,185 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import type { MarketoFormField } from '../types'
+
+const BASIC_FORM_PROPS = {
+	metadata: {
+		result: [
+			{
+				id: 9999,
+				language: 'English',
+				waitingLabel: 'Submitting...',
+				buttonLabel: 'Submit',
+			},
+		],
+	},
+	fields: {
+		result: [
+			{
+				id: 'FirstName',
+				label: 'First Name',
+				dataType: 'text',
+				validationMessage: 'This field is required.',
+				rowNumber: 3,
+				columnNumber: 0,
+				required: true,
+				visibilityRules: {
+					ruleType: 'alwaysShow',
+				},
+			},
+			{
+				id: 'LastName',
+				label: 'Last Name',
+				dataType: 'text',
+				validationMessage: 'This field is required.',
+				rowNumber: 3,
+				columnNumber: 0,
+				required: true,
+				formPrefill: true,
+				visibilityRules: {
+					ruleType: 'alwaysShow',
+				},
+			},
+		] as MarketoFormField[],
+	},
+}
+
+const UTM_FORM_PROPS = {
+	...BASIC_FORM_PROPS,
+	fields: {
+		result: [
+			...BASIC_FORM_PROPS.fields.result,
+			{
+				id: 'utm_medium__c',
+				label: 'utm_medium:',
+				dataType: 'hidden',
+				rowNumber: 7,
+				columnNumber: 0,
+				required: false,
+				autoFill: {
+					value: '',
+					valueFrom: 'query',
+					parameterName: 'utm_medium',
+				},
+				visibilityRules: {
+					ruleType: 'alwaysShow',
+				},
+			},
+			{
+				id: 'form_page_url__c',
+				label: 'form_page_url:',
+				dataType: 'hidden',
+				rowNumber: 7,
+				columnNumber: 0,
+				required: false,
+				visibilityRules: {
+					ruleType: 'alwaysShow',
+				},
+			},
+		] as MarketoFormField[],
+	},
+}
+
+const COOKIE_UTM_FORM_PROPS = {
+	...BASIC_FORM_PROPS,
+	fields: {
+		result: [
+			...BASIC_FORM_PROPS.fields.result,
+			{
+				id: 'utm_content__c',
+				label: 'utm_content:',
+				dataType: 'hidden',
+				rowNumber: 7,
+				columnNumber: 0,
+				required: false,
+				autoFill: {
+					value: '',
+					valueFrom: 'query',
+					parameterName: 'utm_content',
+				},
+				visibilityRules: {
+					ruleType: 'alwaysShow',
+				},
+			},
+		] as MarketoFormField[],
+	},
+}
+
+const VISIBILITY_RULE_FORM_PROPS = {
+	...BASIC_FORM_PROPS,
+	fields: {
+		result: [
+			...BASIC_FORM_PROPS.fields.result,
+			{
+				id: 'Phone',
+				label: 'Phone Number',
+				dataType: 'telephone',
+				validationMessage: 'Must be a phone number.',
+				rowNumber: 6,
+				columnNumber: 0,
+				required: false,
+				formPrefill: true,
+				visibilityRules: {
+					rules: [
+						{
+							subjectField: 'fastTracktoSales',
+							operator: 'is',
+							values: ['yes'],
+							altLabel: 'Phone Number:',
+						},
+					],
+					ruleType: 'show',
+				},
+			},
+			{
+				id: 'fastTracktoSales',
+				label: 'Have salesperson contact me',
+				dataType: 'checkbox',
+				validationMessage: 'This field is required.',
+				rowNumber: 7,
+				columnNumber: 0,
+				required: false,
+				formPrefill: true,
+				fieldMetaData: {
+					initiallyChecked: false,
+				},
+				visibilityRules: {
+					ruleType: 'alwaysShow',
+				},
+			},
+		] as MarketoFormField[],
+	},
+}
+
+const HIDDEN_COOKIE_FIELD_FORM_PROPS = {
+	...BASIC_FORM_PROPS,
+	fields: {
+		result: [
+			...BASIC_FORM_PROPS.fields.result,
+			{
+				id: 'cookieHiddenField',
+				label: 'Cookie Value',
+				dataType: 'hidden',
+				rowNumber: 20,
+				columnNumber: 0,
+				required: false,
+				autoFill: {
+					value: '',
+					valueFrom: 'cookie',
+					parameterName: 'hidden_cookie_field',
+				},
+			},
+		] as MarketoFormField[],
+	},
+}
+
+export {
+	BASIC_FORM_PROPS,
+	UTM_FORM_PROPS,
+	VISIBILITY_RULE_FORM_PROPS,
+	COOKIE_UTM_FORM_PROPS,
+	HIDDEN_COOKIE_FIELD_FORM_PROPS,
+}

package/src/components/marketo-form/form/index.tsx

@@ -0,0 +1,369 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import { useEffect, useMemo, useRef } from 'react'
+import { useForm, FormProvider } from 'react-hook-form'
+import Button from '@hashicorp/react-design-system-components/src/components/button'
+import VisibilityRule from '../partials/visibility-rule'
+import NameField from '../partials/fields/name-field'
+import { FormMetadataContext } from '../contexts/FormMetadata'
+import {
+	convertToRESTFields,
+	groupFields,
+	calculateDefaultValues,
+	segmentIdentify,
+	includesSkippedRecords,
+	STORED_FIELD_NAMES,
+} from '../utils'
+import type {
+	MarketoFormMetadataResponse,
+	MarketoFormFieldsResponse,
+	MarketoFormGroups,
+	MarketoFormComponents,
+	MarketoSubmissionResponse,
+} from '../types'
+
+interface Props {
+	/**
+	 * The Marketo API response containing the metadata of the form.
+	 * See {@link MarketoFormMetadataResponse} for more details.
+	 */
+	metadata: MarketoFormMetadataResponse
+
+	/**
+	 * The Marketo API response containing the fields to render.
+	 * See {@link MarketoFormFieldsResponse} for more details.
+	 */
+	fields: MarketoFormFieldsResponse
+
+	/**
+	 * Configuration on which fields to render with a single component.
+	 * See {@link MarketoFormGroups} for more details.
+	 */
+	groups?: MarketoFormGroups
+
+	/**
+	 * Initial values to use for fields, primarily useful in setting values for
+	 * hidden fields that don't derive their values from URL parameters. Keys are
+	 * SOAP field names.
+	 */
+	initialValues?: Record<string, any>
+
+	/**
+	 * Custom components to be used in lieu of the default built-in components.
+	 * See {@link MarketoFormComponents} for more details.
+	 */
+	components?: MarketoFormComponents
+
+	/**
+	 * Text to use for the submit button. Defaults to "Submit".
+	 */
+	submitTitle?: string
+
+	/**
+	 * Additional class name to apply to the <form> element.
+	 */
+	className?: string
+
+	/**
+	 * Whether to reset the form after a successful submission.
+	 * Default: false
+	 */
+	resetOnSubmission?: boolean
+
+	/**
+	 * Callback called when form has started submission process.
+	 */
+	onSubmitStart?: () => void
+
+	/**
+	 * Callback called when form has been successfully submitted.
+	 */
+	onSubmitSuccess?: () => void
+
+	/**
+	 * Callback called when form submission results in an error.
+	 */
+	onSubmitError?: () => void
+
+	/**
+	 * Callback called after performing validation based on Marketo settings, but
+	 * before rendering error messages. Used to perform validations that aren't
+	 * supported by the Marketo API (such as checking if an email address is
+	 * correctly formatted).
+	 * @param values Map of field IDs to field values
+	 * @param errors Map of field IDs to error messages
+	 */
+	validateFields?: (
+		values: Record<string, string | boolean>,
+		errors: Record<string, { message: string }>
+	) => Promise<{ values: any; errors: Record<string, { message: string }> }>
+
+	/**
+	 * If false, the form will not persist field values in local storage.
+	 * Default: true
+	 */
+	persistFieldValues?: boolean
+
+	/**
+	 * Optional name of form to use for the forms aria-label.
+	 */
+	formName?: string
+}
+
+const defaultFieldGroupings = {
+	name: {
+		fields: ['FirstName', 'LastName'],
+		component: NameField,
+	},
+}
+
+function isValidEmail(value: string): boolean {
+	// Source: https://html.spec.whatwg.org/multipage/input.html#email-state-(type=email)
+	// Slightly modified to require domains instead of bare TLDs
+	/* eslint-disable-next-line no-useless-escape */
+	return /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$/i.test(
+		value
+	)
+}
+
+const Form = ({
+	metadata,
+	fields,
+	groups = defaultFieldGroupings,
+	initialValues,
+	components,
+	submitTitle,
+	className,
+	resetOnSubmission,
+	onSubmitStart,
+	onSubmitSuccess,
+	onSubmitError,
+	validateFields,
+	persistFieldValues = true,
+	formName,
+}: Props) => {
+	// Track if the form has been rendered at least once, so that we know if
+	// react-hook-form has already cached values.
+	const hasBeenRendered = useRef(false)
+
+	// memoized function that groups marketo fields based on supplied groups.
+	// If a field doesn't belong to a group, it is placed in a group keyed by
+	// field.Name.
+	const groupedFields = useMemo(() => {
+		if (!('result' in fields)) {
+			return {}
+		}
+		return groupFields(fields.result, groups)
+	}, [fields, groups])
+
+	const methods = useForm({
+		mode: 'onBlur',
+		defaultValues:
+			'result' in fields
+				? calculateDefaultValues(fields.result, initialValues)
+				: {},
+		resolver: async (values: Record<string, string | boolean>) => {
+			let errors: Record<string, { message: string }> = {}
+
+			fields.result.forEach((field) => {
+				if ('required' in field && field.required) {
+					if (
+						!(field.id in values) ||
+						values[field.id] === '' ||
+						values[field.id] === false ||
+						values[field.id] === undefined ||
+						values[field.id] === null ||
+						(typeof values[field.id] === 'string' &&
+							(values[field.id] as string).trim() === '')
+					) {
+						errors[field.id] = {
+							message: field.validationMessage ?? 'This field is required.',
+						}
+					}
+				}
+
+				// Validate that select field value is an allowed value
+				if (field.dataType === 'select') {
+					if (
+						field.id in values &&
+						field.fieldMetaData.values &&
+						!field.fieldMetaData.values
+							.map((v) => v.value)
+							.includes(values[field.id] as string)
+					) {
+						errors[field.id] = {
+							message: field.validationMessage ?? 'Please select an option.',
+						}
+					}
+				}
+
+				if (field.dataType === 'email') {
+					if (field.id in values && !isValidEmail(values[field.id] as string)) {
+						errors[field.id] = {
+							message:
+								field.validationMessage ??
+								'Please enter a valid email address.',
+						}
+					}
+				}
+			})
+
+			if (validateFields) {
+				const additionalValidations = await validateFields(values, errors)
+				values = additionalValidations.values
+				errors = additionalValidations.errors
+			}
+
+			return { values, errors }
+		},
+	})
+
+	// Reset form if initialValues changes since defaultValues is cached on the
+	// first render. This handles the situation where initialValues is updated
+	// after the form is rendered, primarily when using router state which is
+	// resolved _after_ the initial render for SSG pages.
+	useEffect(() => {
+		if (hasBeenRendered.current) {
+			const storedValues = persistFieldValues
+				? JSON.parse(localStorage.getItem('marketoFormData') || '{}')
+				: null
+			const newValues = calculateDefaultValues(fields.result, {
+				...storedValues,
+				...initialValues,
+			})
+			Object.entries(newValues).forEach(([fieldId, value]) => {
+				if (!methods.getValues(fieldId)) {
+					methods.setValue(fieldId, value)
+				}
+			})
+		}
+	}, [hasBeenRendered, methods, fields, initialValues])
+
+	// Track that we've finished rendering.
+	useEffect(() => {
+		hasBeenRendered.current = true
+	}, [hasBeenRendered])
+
+	const onSubmit = async (data: Record<string, unknown>) => {
+		if (onSubmitStart) {
+			onSubmitStart()
+		}
+		const leadFormFields = convertToRESTFields(data)
+
+		segmentIdentify(leadFormFields)
+
+		const res = await fetch(`${window.location.origin}/api/marketo/submit`, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+			},
+			body: JSON.stringify({
+				input: [
+					{
+						leadFormFields,
+						visitorData: {
+							pageURL: window.location.href,
+						},
+					},
+				],
+				formId: metadata.result[0].id,
+			}),
+		})
+		const marketoResponse = (await res.json()) as MarketoSubmissionResponse
+		if (
+			res.status === 200 &&
+			marketoResponse.success &&
+			!includesSkippedRecords(marketoResponse)
+		) {
+			if (onSubmitSuccess) {
+				onSubmitSuccess()
+			}
+
+			// Remove fields that shouldn't be stored in local storage
+			const dataToPersist = Object.fromEntries(
+				Object.entries(data).filter(([k]) => STORED_FIELD_NAMES.includes(k))
+			)
+			localStorage.setItem('marketoFormData', JSON.stringify(dataToPersist))
+
+			if (resetOnSubmission) {
+				methods.reset()
+			}
+		} else {
+			console.error(marketoResponse)
+			if (onSubmitError) {
+				onSubmitError()
+			}
+
+			throw new Error('An error occurred while submitting form.')
+		}
+	}
+
+	if (fields.success === false || metadata.success === false) {
+		return (
+			<div>
+				<p>This form is currently unavailable. Please try again later.</p>
+			</div>
+		)
+	}
+
+	return (
+		<FormMetadataContext.Provider value={metadata.result[0]}>
+			<FormProvider {...methods}>
+				<form
+					className={className}
+					onSubmit={methods.handleSubmit(onSubmit)}
+					data-marketo-form-id={metadata.result[0].id}
+					aria-label={formName}
+				>
+					{Object.entries(groupedFields).map(([groupName, fields]) => {
+						// If this group name has a custom component defined, use that
+						// instead of the default field components.
+						if (groups && groupName in groups) {
+							const Component = groups[groupName].component
+							return (
+								<Component
+									key={fields.map((f) => f.id).join('-')}
+									fields={fields}
+								/>
+							)
+						}
+
+						if (fields.length > 1) {
+							console.warn(
+								`Multiple fields in group ${groupName} with no component defined.`
+							)
+						}
+
+						return (
+							<VisibilityRule
+								key={fields[0].id}
+								components={components}
+								field={fields[0]}
+							/>
+						)
+					})}
+					<Button
+						type="submit"
+						size="large"
+						disabled={
+							methods.formState.isSubmitting ||
+							(methods.formState.isSubmitSuccessful && !resetOnSubmission)
+						}
+						text={
+							methods.formState.isSubmitting ||
+							(methods.formState.isSubmitSuccessful && !resetOnSubmission)
+								? metadata.result[0].waitingLabel
+								: submitTitle ?? metadata.result[0].buttonLabel
+						}
+					/>
+				</form>
+			</FormProvider>
+		</FormMetadataContext.Provider>
+	)
+}
+
+export { defaultFieldGroupings }
+export default Form