@windstream/react-shared-components 0.2.55 → 0.2.56

package/src/contentful/blocks/dynamic-form/index.tsx

@@ -0,0 +1,552 @@
+"use client";
+
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { constants, DEFAULT_VALIDATION_ERROR_TEXT, Regex } from "./constants";
+import { FormContext, FormContextType } from "./context";
+import { dynamicRenderingWithGroupings } from "./render";
+import {
+  DynamicFormItem,
+  DynamicFormPayload,
+  DynamicFormProps,
+  FormAction,
+  SubmitContext,
+  SubmitHandler,
+} from "./types";
+import {
+  arrayForFieldValidations,
+  buildSftpMap,
+  filterActionsForEmailTemplate,
+  formPayloadCreation,
+  generateSubmissionId,
+  getInvalidFields,
+  shouldShowPopup,
+} from "./utils";
+
+import { Button } from "@shared/components/button";
+import { Spinner } from "@shared/components/spinner";
+import { Text } from "@shared/components/text";
+import { cx } from "@shared/utils";
+
+class FormValidationError extends Error {
+  invalidFields: string[];
+  constructor(message: string, invalidFields: string[]) {
+    super(message);
+    this.name = "FormValidationError";
+    this.invalidFields = invalidFields;
+  }
+}
+
+class FormSubmissionError extends Error {
+  errorActions: FormAction[];
+  isCompleteFailure: boolean;
+  constructor(
+    message: string,
+    errorActions: FormAction[],
+    isCompleteFailure: boolean
+  ) {
+    super(message);
+    this.name = "FormSubmissionError";
+    this.errorActions = errorActions;
+    this.isCompleteFailure = isCompleteFailure;
+  }
+}
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+const formatSubmittedOn = (date: Date): string => {
+  const month = pad(date.getMonth() + 1);
+  const day = pad(date.getDate());
+  const year = date.getFullYear();
+  let hours = date.getHours();
+  const minutes = pad(date.getMinutes());
+  const ampm = hours >= 12 ? "PM" : "AM";
+  hours = hours % 12 || 12;
+  return `${month}/${day}/${year} ${hours}:${minutes} ${ampm}`;
+};
+
+const validateTNandIP = (value: any) => {
+  const trimmed = value?.trim();
+  if (!trimmed) return value;
+  if (Regex.phone.test(trimmed)) {
+    let digits = trimmed.replace(/\D/g, "");
+    if (digits.length === 11 && digits.startsWith("1")) {
+      digits = digits.slice(1);
+    }
+    return digits;
+  }
+  if (Regex.ipv4.test(trimmed) || Regex.ipv6.test(trimmed)) {
+    return trimmed;
+  }
+  return value;
+};
+
+export const DynamicForm: React.FC<DynamicFormProps> = props => {
+  const {
+    anchorId,
+    title,
+    subTitle,
+    formHeading,
+    description,
+    disclaimer,
+    successMessage,
+    errorMessage: errorNode,
+    formClassName,
+    fields,
+    formSubmitOptions = [],
+    submitLabel = "Submit",
+    ctaClassName,
+    validationErrorText = DEFAULT_VALIDATION_ERROR_TEXT,
+    formName,
+    emailSubject,
+    emailTemplateName,
+    toEmail,
+    segmentEventId,
+    onEmailSubmit,
+    onSmtpSubmit,
+    onSmsSubmit,
+    actionHandlers,
+    buildPayload,
+    onSubmitSuccess,
+    onTrack,
+    onError,
+    fieldComponentOverrides,
+    resolveExistingDataSource,
+  } = props;
+
+  const submissionIdRef = useRef<string>(generateSubmissionId());
+  const successRef = useRef<HTMLDivElement>(null);
+
+  const [formData, setFormData] = useState<Record<string, any>>({});
+  const [isLoading, setIsLoading] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+  const [hasError, setHasError] = useState(false);
+  const [submitError, setSubmitError] = useState(false);
+  const [submitErrorFields, setSubmitErrorFields] = useState<string[]>([]);
+  const [validationMessage, setValidationMessage] = useState("");
+  const [selectedState, setSelectedState] = useState<any>(null);
+  const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({});
+  const [files, setFiles] = useState<File[]>([]);
+
+  const updateFiles = useCallback((nextFiles: File[]) => {
+    setFiles(nextFiles);
+  }, []);
+
+  const addFieldError = useCallback((fieldId: string, message: string) => {
+    setFieldErrors(prev => ({ ...prev, [fieldId]: message }));
+  }, []);
+
+  const clearFieldError = useCallback((fieldId: string) => {
+    setFieldErrors(prev => {
+      const next = { ...prev };
+      delete next[fieldId];
+      return next;
+    });
+  }, []);
+
+  const groupedValidationGroups = useMemo(() => {
+    return fields.reduce((acc: Record<string, any[]>, item) => {
+      if (item.itemType !== "formField") return acc;
+      const group = item.validationGroupId;
+      if (group != undefined && group != null) {
+        if (!acc[group]) acc[group] = [];
+        acc[group].push(item);
+      }
+      return acc;
+    }, {});
+  }, [fields]);
+
+  useEffect(() => {
+    if (submitted && typeof window !== "undefined" && successRef.current) {
+      const navbarHeight = 140;
+      const offsetPosition = successRef.current.offsetTop - navbarHeight;
+      window.scrollTo({ top: offsetPosition, behavior: "smooth" });
+    }
+  }, [submitted]);
+
+  const contextValue: FormContextType = useMemo(
+    () => ({
+      fieldErrors,
+      setFieldError: addFieldError,
+      clearFieldError,
+      hasError,
+      setHasError,
+      selectedState,
+      setSelectedState,
+      files,
+      setFiles: updateFiles,
+      resolveExistingDataSource,
+      fieldComponentOverrides,
+      onError,
+    }),
+    [
+      fieldErrors,
+      addFieldError,
+      clearFieldError,
+      hasError,
+      selectedState,
+      files,
+      updateFiles,
+      resolveExistingDataSource,
+      fieldComponentOverrides,
+      onError,
+    ]
+  );
+
+  const applyPresetValidations = (): Record<string, any> => {
+    const updatedData = { ...formData };
+    fields.forEach(item => {
+      if (item.itemType !== "formField") return;
+      if (
+        item.applyPresetValidations &&
+        item.selectPresetValidationsToApply === "TN-IP-Validation"
+      ) {
+        updatedData[item.fieldId] = validateTNandIP(updatedData[item.fieldId]);
+      }
+    });
+    setFormData(updatedData);
+    return updatedData;
+  };
+
+  const handlerMap: Partial<Record<FormAction, SubmitHandler>> = useMemo(
+    () => ({
+      email: onEmailSubmit,
+      sftp: onSmtpSubmit,
+      sms: onSmsSubmit,
+      ...(actionHandlers || {}),
+    }),
+    [onEmailSubmit, onSmtpSubmit, onSmsSubmit, actionHandlers]
+  );
+
+  const runActions = async (
+    actions: FormAction[],
+    payload: DynamicFormPayload,
+    baseContext: Omit<SubmitContext, "action" | "options">
+  ): Promise<{ error: boolean; errorActions: FormAction[] }> => {
+    const errorActions: FormAction[] = [];
+    const formDataString = JSON.stringify({ ...payload.formData });
+
+    let body: DynamicFormPayload | FormData;
+    if (payload.files && payload.files.length > 0) {
+      const fd = new FormData();
+      Object.keys(payload).forEach(key => {
+        if (key === "files" || key === "formData") return;
+        fd.append(key, (payload as any)[key]);
+      });
+      fd.append("formData", formDataString);
+      payload.files.forEach(file => fd.append("files", file));
+      body = fd;
+    } else {
+      body = { ...payload, formData: formDataString } as any;
+    }
+
+    const effectiveActions = filterActionsForEmailTemplate(
+      actions,
+      payload.emailTemplate
+    );
+
+    await Promise.all(
+      effectiveActions.map(async action => {
+        const handler = handlerMap[action];
+        const options =
+          body instanceof FormData
+            ? { headers: { "Content-Type": undefined } }
+            : {};
+        if (handler) {
+          try {
+            await handler(body, { ...baseContext, action, options });
+            onTrack?.(`${segmentEventId}_${action}_success`, {
+              ...payload,
+              eventSuccess: true,
+            });
+          } catch (error) {
+            errorActions.push(action);
+            onTrack?.(`${segmentEventId}_${action}_failure`, {
+              ...payload,
+              eventSuccess: false,
+            });
+            onError?.({
+              type: "action_failure",
+              error,
+              metadata: { action, submissionId: submissionIdRef.current },
+            });
+          }
+        } else {
+          errorActions.push(action);
+          onTrack?.(`${segmentEventId}_${action}_failure`, {
+            ...payload,
+            eventSuccess: false,
+          });
+          onError?.({
+            type: "unsupported_action",
+            error: new Error(`Action "${action}" is not supported`),
+            metadata: { action },
+          });
+        }
+      })
+    );
+
+    return { error: errorActions.length > 0, errorActions };
+  };
+
+  const handleSubmit = async (event: any): Promise<void> => {
+    event.preventDefault();
+    setIsLoading(true);
+    setValidationMessage("");
+
+    const newFormData = applyPresetValidations();
+
+    try {
+      const extractedArray = arrayForFieldValidations(fields, false, newFormData);
+      const sftpMap = buildSftpMap(fields, newFormData);
+      const invalidFields = getInvalidFields(extractedArray, newFormData);
+      setSubmitErrorFields(invalidFields);
+
+      Object.keys(groupedValidationGroups).forEach(groupId => {
+        const groupFields = groupedValidationGroups[groupId];
+        const fieldIds = groupFields.map(item => item.fieldId);
+        const invalidCase = groupFields.filter(field => {
+          if (field.validationType === constants.ONE_REQUIRED_FIELD) {
+            return (
+              newFormData[field.fieldId] === "" ||
+              newFormData[field.fieldId] === undefined
+            );
+          }
+          return false;
+        });
+        if (
+          invalidCase.length === groupFields.length &&
+          groupFields.length > 0
+        ) {
+          setSubmitErrorFields(prev => [...prev, ...fieldIds]);
+          throw new FormValidationError(
+            constants.REQUIRED_FIELDS_MISSING,
+            fieldIds
+          );
+        }
+      });
+
+      if (invalidFields.length !== 0 || Object.keys(fieldErrors).length !== 0) {
+        throw new FormValidationError(
+          constants.REQUIRED_FIELDS_MISSING,
+          invalidFields
+        );
+      }
+
+      const formPayload = formPayloadCreation(fields, newFormData);
+      const basePayload: DynamicFormPayload = {
+        submissionId: submissionIdRef.current,
+        formName,
+        toEmail,
+        subject: emailSubject,
+        emailTemplate: emailTemplateName,
+        submittedOn: formatSubmittedOn(new Date()),
+        formSubmitOptions,
+        formData: formPayload,
+        files,
+      };
+
+      const payload = buildPayload
+        ? buildPayload(basePayload, newFormData)
+        : basePayload;
+
+      onTrack?.(segmentEventId, payload);
+
+      const actions = payload.formSubmitOptions || [];
+      const hasPost = actions.includes("post");
+      const serverActions = actions.filter(a => a !== "post");
+
+      const res = await runActions(serverActions, payload, {
+        payload,
+        formValues: newFormData,
+        sftpMap,
+        formSubmitOptions: actions,
+        files,
+      });
+
+      if (res.error && serverActions.length === res.errorActions.length) {
+        throw new FormSubmissionError(
+          "All form actions failed",
+          res.errorActions,
+          true
+        );
+      } else if (res.error) {
+        throw new FormSubmissionError(
+          "Some form actions failed",
+          res.errorActions,
+          false
+        );
+      }
+
+      setIsLoading(false);
+      setSubmitted(true);
+
+      if (hasPost) {
+        const postHandler = handlerMap.post;
+        if (postHandler) {
+          await postHandler({ ...payload } as any, {
+            payload,
+            formValues: newFormData,
+            sftpMap,
+            formSubmitOptions: actions,
+            files,
+            action: "post",
+            options: {},
+          });
+        }
+      }
+
+      if (shouldShowPopup(fields, newFormData)) {
+        onSubmitSuccess?.(newFormData, { shouldShowPopup: true });
+      } else {
+        onSubmitSuccess?.(newFormData, { shouldShowPopup: false });
+      }
+    } catch (error) {
+      let errorType = "unknown";
+      if (error instanceof FormValidationError) {
+        errorType = "validation";
+        setValidationMessage(validationErrorText);
+      } else if (error instanceof FormSubmissionError) {
+        errorType = error.isCompleteFailure
+          ? "complete_submission_failure"
+          : "partial_submission_failure";
+        if (error.isCompleteFailure) {
+          setSubmitted(false);
+          setSubmitError(true);
+        } else {
+          setSubmitted(true);
+          setSubmitError(false);
+        }
+      } else {
+        errorType = "unexpected";
+        setValidationMessage(
+          "An error occurred while submitting the form. Please try again later."
+        );
+        setSubmitError(true);
+        setSubmitted(false);
+      }
+
+      onError?.({
+        type: errorType,
+        error,
+        metadata: {
+          formName,
+          submissionId: submissionIdRef.current,
+          formSubmitOptions,
+          segmentEventId,
+        },
+      });
+
+      setIsLoading(false);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  if (submitted) {
+    return (
+      <div
+        ref={successRef}
+        className="mx-auto min-h-screen w-full px-4 sm:px-6 lg:px-8"
+      >
+        <div className="max-w-2xl mx-auto py-4 sm:py-6 lg:py-8">
+          {successMessage}
+        </div>
+      </div>
+    );
+  }
+
+  if (submitError) {
+    return (
+      <div className="mx-auto min-h-screen w-full px-4 sm:px-6 lg:px-8">
+        <div className="max-w-2xl mx-auto py-4 sm:py-6 lg:py-8">
+          {errorNode}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <section id={anchorId} aria-labelledby={`${anchorId}-title`}>
+      <div className="mx-auto min-h-screen max-w-[800px] px-5 py-8 md:px-5 md:py-20">
+        <div className="pb-8 sm:pb-6 lg:pb-4">
+          <div className="mb-8 lg:mb-16">
+            {title && (
+              <Text as="h2" className="heading2 text-center">
+                {title}
+              </Text>
+            )}
+            {subTitle && (
+              <Text as="h3" className="subheading3 mt-3 text-center">
+                {subTitle}
+              </Text>
+            )}
+          </div>
+          {description ? (
+            <div className="text-center">{description}</div>
+          ) : null}
+          {formHeading ? (
+            <div className="mb-6 w-full px-2 sm:px-4">
+              <Text
+                as="div"
+                className="body3 mb-2 text-center text-xl sm:mb-4 md:text-left"
+              >
+                {formHeading}
+              </Text>
+            </div>
+          ) : null}
+          <div className="mt-8 md:mt-16">
+            <FormContext.Provider value={contextValue}>
+              <form
+                onSubmit={handleSubmit}
+                className={cx(
+                  "flex w-full flex-col gap-5 md:gap-8",
+                  formClassName
+                )}
+              >
+                {dynamicRenderingWithGroupings(
+                  isLoading,
+                  fields as DynamicFormItem[],
+                  formData,
+                  setFormData,
+                  submitErrorFields
+                )}
+                {validationMessage && (
+                  <Text as="div" className="footnote text-text-critical">
+                    {validationMessage}
+                  </Text>
+                )}
+                <div className="flex justify-center">
+                  <Button
+                    type="submit"
+                    disabled={hasError || isLoading}
+                    aria-label="Submit Form"
+                    className={cx(
+                      "button-submit mt-3 inline-flex h-[64px] w-full items-center justify-center gap-2 whitespace-nowrap rounded-full bg-bg-fill-brand px-[60px] text-base font-semibold text-text-brand-on-bg-fill transition hover:bg-bg-fill-brand-hover disabled:bg-bg-fill-brand-disabled md:mt-8 md:w-auto",
+                      ctaClassName
+                    )}
+                  >
+                    {isLoading && <Spinner />}
+                    {submitLabel}
+                  </Button>
+                </div>
+              </form>
+            </FormContext.Provider>
+          </div>
+          {disclaimer && (
+            <Text as="div" className="footnote m-2">
+              {disclaimer}
+            </Text>
+          )}
+        </div>
+      </div>
+    </section>
+  );
+};
+
+export default DynamicForm;

package/src/contentful/blocks/dynamic-form/render.test.tsx

@@ -0,0 +1,116 @@
+import React from "react";
+import { constants } from "./constants";
+import { FormContext, FormContextType } from "./context";
+import { dynamicRenderingWithGroupings } from "./render";
+import { DynamicFormItem } from "./types";
+
+import { render, screen } from "@testing-library/react";
+
+const context: FormContextType = {
+  fieldErrors: {},
+  setFieldError: jest.fn(),
+  clearFieldError: jest.fn(),
+  hasError: false,
+  setHasError: jest.fn(),
+  selectedState: null,
+  setSelectedState: jest.fn(),
+  files: [],
+  setFiles: jest.fn(),
+};
+
+const renderGroups = (fields: DynamicFormItem[]) =>
+  render(
+    <FormContext.Provider value={context}>
+      {dynamicRenderingWithGroupings(false, fields, {}, jest.fn(), [])}
+    </FormContext.Provider>
+  );
+
+const field = (
+  overrides: Partial<Extract<DynamicFormItem, { itemType: "formField" }>>
+): DynamicFormItem => ({
+  itemType: "formField",
+  fieldId: "f",
+  fieldType: "Text",
+  displayName: "Field",
+  ...overrides,
+});
+
+describe("dynamicRenderingWithGroupings", () => {
+  it("renders a single full-width field", () => {
+    renderGroups([field({ fieldId: "a", displayName: "Full Field" })]);
+    expect(screen.getByText("Full Field")).toBeInTheDocument();
+  });
+
+  it("renders two half-width fields as a double group", () => {
+    renderGroups([
+      field({ fieldId: "a", displayName: "Left", fieldWidth: false }),
+      field({ fieldId: "b", displayName: "Right", fieldWidth: false }),
+    ]);
+    expect(screen.getByText("Left")).toBeInTheDocument();
+    expect(screen.getByText("Right")).toBeInTheDocument();
+  });
+
+  it("renders a custom pass-through item", () => {
+    renderGroups([
+      { itemType: "custom", content: <div>Custom Content</div> },
+    ]);
+    expect(screen.getByText("Custom Content")).toBeInTheDocument();
+  });
+
+  it("renders a conditional item", () => {
+    renderGroups([
+      {
+        itemType: "conditional",
+        fieldId: "cond",
+        displayName: "Conditional?",
+        dataSource: [{ label: "Yes", value: "yes" }],
+        formFieldsToShow: [],
+      },
+    ]);
+    expect(screen.getByText("Conditional?")).toBeInTheDocument();
+  });
+
+  it("renders a validation group with single and double subgroups and a required marker", () => {
+    const { container } = renderGroups([
+      field({
+        fieldId: "g1",
+        displayName: "Group A",
+        validationGroupId: "grp",
+        validationNote: "Provide at least one",
+        validationType: constants.ONE_REQUIRED_FIELD,
+        fieldWidth: false,
+      }),
+      field({
+        fieldId: "g2",
+        displayName: "Group B",
+        validationGroupId: "grp",
+        fieldWidth: false,
+      }),
+      field({
+        fieldId: "g3",
+        displayName: "Group C",
+        validationGroupId: "grp",
+        fieldWidth: true,
+      }),
+    ]);
+    expect(screen.getByText("Provide at least one")).toBeInTheDocument();
+    expect(screen.getByText("Group A")).toBeInTheDocument();
+    expect(screen.getByText("Group C")).toBeInTheDocument();
+    expect(container.querySelector(".text-text-critical")).toHaveTextContent(
+      "*"
+    );
+  });
+
+  it("renders a validation group without a required marker for other validation types", () => {
+    renderGroups([
+      field({
+        fieldId: "g1",
+        displayName: "Group Only",
+        validationGroupId: "grp2",
+        validationNote: "Optional group note",
+        validationType: "Some Other Type",
+      }),
+    ]);
+    expect(screen.getByText("Optional group note")).toBeInTheDocument();
+  });
+});