@windstream/react-shared-components 0.2.55 → 0.2.56

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

@@ -0,0 +1,172 @@
+"use client";
+
+import React from "react";
+import ConditionalFormFields from "./conditional-fields";
+import { constants } from "./constants";
+import FormFieldElement from "./form-field";
+import { DynamicFormItem } from "./types";
+import { groupFieldsForLayout } from "./utils";
+
+import { Text } from "@shared/components/text";
+
+type FormValues = Record<string, any>;
+type SetFormData = (updater: (prev: FormValues) => FormValues) => void;
+
+const renderItem = (
+  item: DynamicFormItem,
+  key: string,
+  isLoading: boolean,
+  formData: FormValues,
+  setFormData: SetFormData,
+  submitErrorFields: string[],
+  isGrouped = false
+): React.ReactNode => {
+  if (item.itemType === "formField") {
+    return (
+      <FormFieldElement
+        key={key}
+        loading={isLoading}
+        {...item}
+        formData={formData}
+        setFormData={setFormData}
+        submitErrorFields={submitErrorFields}
+        isGrouped={isGrouped}
+      />
+    );
+  }
+  if (item.itemType === "conditional") {
+    return (
+      <ConditionalFormFields
+        key={key}
+        {...item}
+        formData={formData}
+        setFormData={setFormData}
+        submitErrorFields={submitErrorFields}
+      />
+    );
+  }
+  return <React.Fragment key={key}>{item.content}</React.Fragment>;
+};
+
+export const dynamicRenderingWithGroupings = (
+  isLoading: boolean,
+  fields: DynamicFormItem[],
+  formData: FormValues,
+  setFormData: SetFormData,
+  submitErrorFields: string[]
+): React.ReactNode[] => {
+  return groupFieldsForLayout(fields).map((group, groupIndex) => {
+    if (group.type === "validationGroup") {
+      return (
+        <div
+          key={`validation-group-${groupIndex}`}
+          className="mb-0 w-full rounded-b-xl rounded-t-xl border border-border-secondary bg-bg-surface-secondary px-5 pb-5 pt-1"
+        >
+          {group.validationNote && (
+            <Text as="div" className="validation-label body3 mb-3 mt-4 sm:mt-5">
+              {group.validationNote}
+              {group.validationType === constants.ONE_REQUIRED_FIELD ? (
+                <span className="text-text-critical">*</span>
+              ) : null}
+            </Text>
+          )}
+          {group.subGroups.map((subGroup: any, subGroupIndex: number) => {
+            if (subGroup.type === "single") {
+              return (
+                <div key={`subgroup-${subGroupIndex}`} className="mb-0 w-full">
+                  {renderItem(
+                    subGroup.fields[0],
+                    `subgroup-field-${subGroupIndex}`,
+                    isLoading,
+                    formData,
+                    setFormData,
+                    submitErrorFields,
+                    true
+                  )}
+                </div>
+              );
+            }
+            return (
+              <div
+                key={`subgroup-${subGroupIndex}`}
+                className="mb-0 flex w-full flex-col gap-5 lg:flex-row"
+              >
+                <div className="w-full lg:flex-1">
+                  {renderItem(
+                    subGroup.fields[0],
+                    `subgroup-field-${subGroupIndex}-0`,
+                    isLoading,
+                    formData,
+                    setFormData,
+                    submitErrorFields,
+                    true
+                  )}
+                </div>
+                <div className="w-full lg:flex-1">
+                  {renderItem(
+                    subGroup.fields[1],
+                    `subgroup-field-${subGroupIndex}-1`,
+                    isLoading,
+                    formData,
+                    setFormData,
+                    submitErrorFields,
+                    true
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      );
+    }
+
+    if (group.type === "single") {
+      const field = group.fields[0] as DynamicFormItem;
+      const className =
+        field.itemType === "formField"
+          ? `${field.fieldClassName?.split("|")[0] ?? ""} mb-0 w-full`
+          : "w-full";
+      return (
+        <div key={`group-${groupIndex}`} className={className}>
+          {renderItem(
+            field,
+            `group-field-${groupIndex}`,
+            isLoading,
+            formData,
+            setFormData,
+            submitErrorFields
+          )}
+        </div>
+      );
+    }
+
+    // double
+    return (
+      <div
+        key={`group-${groupIndex}`}
+        className="mb-0 flex w-full flex-col gap-5 lg:flex-row"
+      >
+        <div className="w-full lg:flex-1">
+          {renderItem(
+            group.fields[0],
+            `group-field-${groupIndex}-0`,
+            isLoading,
+            formData,
+            setFormData,
+            submitErrorFields
+          )}
+        </div>
+        <div className="w-full lg:flex-1">
+          {renderItem(
+            group.fields[1],
+            `group-field-${groupIndex}-1`,
+            isLoading,
+            formData,
+            setFormData,
+            submitErrorFields
+          )}
+        </div>
+      </div>
+    );
+  });
+};

package/src/contentful/blocks/dynamic-form/types.ts

@@ -0,0 +1,211 @@
+import React from "react";
+
+/**
+ * The set of submit actions the DynamicForm understands. Each maps to an
+ * injected async handler provided by the consuming application. The package
+ * owns the UI, validation, payload building and orchestration; the app owns
+ * the actual transport (HTTP calls, redirects, etc.).
+ */
+export type FormAction = "email" | "sftp" | "sms" | "voice" | "post";
+
+export type DynamicFormFieldType =
+  | "Text"
+  | "Checkbox"
+  | "Radio"
+  | "Dropdown"
+  | "Datepicker"
+  | "Imageupload";
+
+export interface DynamicFormFieldOption {
+  label: string;
+  value: string;
+  /** When true, selecting this option should trigger the success popup. */
+  popup?: boolean;
+  [key: string]: any;
+}
+
+/**
+ * A single, Contentful-agnostic form field descriptor. The consuming app is
+ * responsible for transforming its CMS entries into this plain shape.
+ */
+export interface DynamicFormFieldConfig {
+  fieldId: string;
+  fieldType: DynamicFormFieldType;
+  displayName?: string;
+  requiredField?: boolean;
+  textInputType?: "phone" | "email" | "multiline" | string;
+  errorMessage?: string;
+  dataSource?: DynamicFormFieldOption[] | null;
+  existingDataSource?: string;
+  note?: string;
+  noteClassName?: string;
+  fieldClassName?: string;
+  /** true => full width, false => half width, undefined => full width. */
+  fieldWidth?: boolean;
+  validationGroupId?: string;
+  validationType?: string;
+  validationNote?: string;
+  formSection?: string;
+  sftpFieldId?: string;
+  applyRegularExpression?: boolean;
+  regexPattern?: string;
+  applyPresetValidations?: boolean;
+  selectPresetValidationsToApply?: string;
+}
+
+export interface ConditionalFieldConfig {
+  fieldId: string;
+  displayName?: string;
+  requiredField?: boolean;
+  dataSource?: DynamicFormFieldOption[] | null;
+  note?: string;
+  formFieldsToShow: DynamicFormItem[];
+}
+
+/**
+ * A flat list item rendered by the form. Either a form field, a conditional
+ * field group, or an arbitrary pre-rendered node (e.g. a nested CMS block that
+ * the app rendered itself and passes through).
+ */
+export type DynamicFormItem =
+  | ({ itemType: "formField" } & DynamicFormFieldConfig)
+  | ({ itemType: "conditional" } & ConditionalFieldConfig)
+  | { itemType: "custom"; fieldId?: string; content: React.ReactNode };
+
+export interface DynamicFormPayload {
+  submissionId: string;
+  formName?: string;
+  subject?: string;
+  emailTemplate?: string;
+  submittedOn: string;
+  formSubmitOptions: FormAction[];
+  /** Grouped form data, keyed by form section. */
+  formData: Record<string, any>;
+  files: File[];
+  toEmail?: string;
+  toPhone?: string;
+  toSms?: string;
+  [key: string]: any;
+}
+
+export interface SubmitContext {
+  /** The structured payload (as built by the form, before transport encoding). */
+  payload: DynamicFormPayload;
+  /** The raw flat form values keyed by fieldId. */
+  formValues: Record<string, any>;
+  /** Map of fieldId -> sftpFieldId for SMTP/SFTP payload mapping. */
+  sftpMap: Record<string, string>;
+  formSubmitOptions: FormAction[];
+  files: File[];
+  /** The action currently being executed. */
+  action: FormAction;
+  /** Transport hints (e.g. for FormData uploads). */
+  options: Record<string, any>;
+}
+
+/**
+ * Injected transport for a single action. `body` is the ready-to-send payload
+ * (a plain object with a stringified `formData`, or a `FormData` instance when
+ * files are present). Handlers that need to build their own body (e.g. SMTP)
+ * can use `context.formValues` and `context.sftpMap` instead.
+ */
+export type SubmitHandler = (
+  body: DynamicFormPayload | FormData,
+  context: SubmitContext
+) => Promise<any> | any;
+
+export interface FieldRenderProps {
+  loading?: boolean;
+  displayName?: string;
+  requiredField?: boolean;
+  formData: Record<string, any>;
+  fieldId?: string;
+  textInputType?: string;
+  handleInputChange: (event: any) => void;
+  dataSource?: DynamicFormFieldOption[] | null;
+  error: { fieldId?: string; errorMessage: string };
+  errorClass: string;
+  hasError: boolean;
+  existingDataSource?: string;
+  isConsentCheckbox?: boolean;
+  [key: string]: any;
+}
+
+/**
+ * Resolves the options for a field that references an app-owned data source
+ * (e.g. "State List" / "City List"). Injected by the app so the package stays
+ * transport-agnostic.
+ */
+export type ExistingDataSourceResolver = (
+  name: string,
+  ctx: { selectedState?: any }
+) => Promise<DynamicFormFieldOption[]>;
+
+export interface DynamicFormProps {
+  anchorId?: string;
+  title?: string;
+  subTitle?: string;
+  formHeading?: string;
+  /** Pre-rendered rich text supplied by the app. */
+  description?: React.ReactNode;
+  disclaimer?: React.ReactNode;
+  successMessage?: React.ReactNode;
+  errorMessage?: React.ReactNode;
+  formClassName?: string;
+  fields: DynamicFormItem[];
+  formSubmitOptions?: FormAction[];
+
+  /** CTA */
+  submitLabel?: string;
+  ctaClassName?: string;
+
+  /** Copy overrides */
+  validationErrorText?: string;
+
+  /** Payload metadata */
+  formName?: string;
+  emailSubject?: string;
+  emailTemplateName?: string;
+  toEmail?: string;
+  segmentEventId?: string;
+
+  /** Injected per-action async submit handlers. */
+  onEmailSubmit?: SubmitHandler;
+  onSmtpSubmit?: SubmitHandler;
+  onSmsSubmit?: SubmitHandler;
+  /** Optional additional handlers for extra actions (voice/post/custom). */
+  actionHandlers?: Partial<Record<FormAction, SubmitHandler>>;
+
+  /**
+   * Allows the app to mutate the base payload before actions run
+   * (e.g. custom email routing, non-prod rerouting, adding toPhone/toSms).
+   */
+  buildPayload?: (
+    basePayload: DynamicFormPayload,
+    formValues: Record<string, any>
+  ) => DynamicFormPayload;
+
+  /** Called after a successful (or partial) submission. */
+  onSubmitSuccess?: (
+    formValues: Record<string, any>,
+    meta: { shouldShowPopup: boolean }
+  ) => void;
+
+  /** Injected analytics + logging. */
+  onTrack?: (eventId: string | undefined, payload: any) => void;
+  onError?: (info: {
+    type: string;
+    error: unknown;
+    metadata?: Record<string, any>;
+  }) => void;
+
+  /** Whether the current environment is production (affects nothing in the
+   * base component today but reserved for parity with app behavior). */
+  isProduction?: boolean;
+
+  /** Field customization + async data. */
+  fieldComponentOverrides?: Partial<
+    Record<DynamicFormFieldType, React.FC<FieldRenderProps>>
+  >;
+  resolveExistingDataSource?: ExistingDataSourceResolver;
+}

package/src/contentful/blocks/dynamic-form/utils.test.ts

@@ -0,0 +1,238 @@
+import { DynamicFormItem } from "./types";
+import {
+  arrayForFieldValidations,
+  buildSftpMap,
+  filterActionsForEmailTemplate,
+  formPayloadCreation,
+  generateSubmissionId,
+  getInvalidFields,
+  groupFieldsForLayout,
+  processFields,
+  shouldShowPopup,
+} from "./utils";
+
+const textField = (
+  overrides: Partial<Extract<DynamicFormItem, { itemType: "formField" }>> = {}
+): DynamicFormItem => ({
+  itemType: "formField",
+  fieldId: "firstName",
+  fieldType: "Text",
+  requiredField: true,
+  ...overrides,
+});
+
+describe("dynamic-form/utils", () => {
+  describe("generateSubmissionId", () => {
+    it("returns a non-empty string", () => {
+      const id = generateSubmissionId();
+      expect(typeof id).toBe("string");
+      expect(id.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("processFields", () => {
+    it("expands conditional fields when trigger value is 'yes'", () => {
+      const items: DynamicFormItem[] = [
+        {
+          itemType: "conditional",
+          fieldId: "hasAccount",
+          formFieldsToShow: [textField({ fieldId: "accountId" })],
+        },
+      ];
+      expect(processFields(items, { hasAccount: "yes" })).toHaveLength(2);
+      expect(processFields(items, { hasAccount: "no" })).toHaveLength(1);
+    });
+  });
+
+  describe("getInvalidFields", () => {
+    it("flags missing required fields", () => {
+      const arr = arrayForFieldValidations([textField()], false, {});
+      expect(getInvalidFields(arr, {})).toEqual(["firstName"]);
+      expect(getInvalidFields(arr, { firstName: "Jane" })).toEqual([]);
+    });
+
+    it("treats an unchecked consent checkbox as invalid", () => {
+      const arr = arrayForFieldValidations(
+        [
+          textField({
+            fieldId: "consent",
+            fieldType: "Checkbox",
+            dataSource: null,
+          }),
+        ],
+        false,
+        {}
+      );
+      expect(getInvalidFields(arr, { consent: false })).toEqual(["consent"]);
+      expect(getInvalidFields(arr, { consent: true })).toEqual([]);
+    });
+  });
+
+  describe("buildSftpMap", () => {
+    it("maps fieldId to sftpFieldId", () => {
+      const map = buildSftpMap(
+        [textField({ fieldId: "firstName", sftpFieldId: "FNAME" })],
+        {}
+      );
+      expect(map).toEqual({ firstName: "FNAME" });
+    });
+  });
+
+  describe("formPayloadCreation", () => {
+    it("groups by section when all fields declare one", () => {
+      const items = [
+        textField({ fieldId: "a", formSection: "s1" }),
+        textField({ fieldId: "b", formSection: "s1" }),
+      ];
+      const payload = formPayloadCreation(items, { a: "1", b: "2" });
+      expect(payload).toEqual({ s1: [{ a: "1" }, { b: "2" }] });
+    });
+
+    it("falls back to form1 when no section is present", () => {
+      const payload = formPayloadCreation([textField({ fieldId: "a" })], {
+        a: "1",
+      });
+      expect(payload).toEqual({ form1: { a: "1" } });
+    });
+  });
+
+  describe("filterActionsForEmailTemplate", () => {
+    it("drops email action when no template is provided", () => {
+      expect(
+        filterActionsForEmailTemplate(["email", "sms"], undefined)
+      ).toEqual(["sms"]);
+    });
+
+    it("keeps email action when a template is provided", () => {
+      expect(
+        filterActionsForEmailTemplate(["email", "sms"], "welcome")
+      ).toEqual(["email", "sms"]);
+    });
+  });
+
+  describe("shouldShowPopup", () => {
+    it("returns true when the selected option is flagged for popup", () => {
+      const items: DynamicFormItem[] = [
+        textField({
+          fieldId: "topic",
+          fieldType: "Dropdown",
+          dataSource: [
+            { label: "A", value: "a" },
+            { label: "B", value: "b", popup: true },
+          ],
+        }),
+      ];
+      expect(shouldShowPopup(items, { topic: "b" })).toBe(true);
+      expect(shouldShowPopup(items, { topic: "a" })).toBe(false);
+    });
+  });
+
+  describe("groupFieldsForLayout", () => {
+    it("pairs two consecutive half-width fields into a double group", () => {
+      const groups = groupFieldsForLayout([
+        textField({ fieldId: "a", fieldWidth: false }),
+        textField({ fieldId: "b", fieldWidth: false }),
+      ]);
+      expect(groups).toHaveLength(1);
+      expect(groups[0].type).toBe("double");
+    });
+
+    it("keeps a lone half-width field as a single group", () => {
+      const groups = groupFieldsForLayout([
+        textField({ fieldId: "a", fieldWidth: false }),
+        textField({ fieldId: "b", fieldWidth: true }),
+      ]);
+      expect(groups[0].type).toBe("single");
+    });
+
+    it("does not pair a half-width field with a following grouped field", () => {
+      const groups = groupFieldsForLayout([
+        textField({ fieldId: "a", fieldWidth: false }),
+        textField({
+          fieldId: "b",
+          fieldWidth: false,
+          validationGroupId: "grp",
+          validationType: "At least One Required",
+        }),
+      ]);
+      expect(groups[0].type).toBe("single");
+      expect(groups[1].type).toBe("validationGroup");
+    });
+
+    it("wraps a non-form item as its own single group", () => {
+      const groups = groupFieldsForLayout([
+        { itemType: "custom", content: null },
+        textField({ fieldId: "a" }),
+      ]);
+      expect(groups[0].type).toBe("single");
+    });
+
+    it("builds double subgroups inside a validation group", () => {
+      const groups = groupFieldsForLayout([
+        textField({
+          fieldId: "a",
+          fieldWidth: false,
+          validationGroupId: "grp",
+        }),
+        textField({
+          fieldId: "b",
+          fieldWidth: false,
+          validationGroupId: "grp",
+        }),
+        textField({
+          fieldId: "c",
+          fieldWidth: true,
+          validationGroupId: "grp",
+        }),
+      ]);
+      expect(groups[0].type).toBe("validationGroup");
+      expect(groups[0].subGroups[0].type).toBe("double");
+      expect(groups[0].subGroups[1].type).toBe("single");
+    });
+  });
+
+  describe("shouldShowPopup edge cases", () => {
+    it("ignores fields without an array data source", () => {
+      const items: DynamicFormItem[] = [
+        textField({ fieldId: "x", dataSource: null }),
+      ];
+      expect(shouldShowPopup(items, { x: "anything" })).toBe(false);
+    });
+
+    it("returns false when the selected option has no popup flag", () => {
+      const items: DynamicFormItem[] = [
+        textField({
+          fieldId: "topic",
+          dataSource: [{ label: "A", value: "a" }],
+        }),
+      ];
+      expect(shouldShowPopup(items, { topic: "a" })).toBe(false);
+    });
+
+    it("ignores conditional items", () => {
+      const items: DynamicFormItem[] = [
+        {
+          itemType: "conditional",
+          fieldId: "cond",
+          formFieldsToShow: [],
+        },
+      ];
+      expect(shouldShowPopup(items, {})).toBe(false);
+    });
+  });
+
+  describe("generateSubmissionId fallback", () => {
+    it("uses the RFC4122 fallback when crypto.randomUUID is unavailable", () => {
+      const originalRandomUUID = (crypto as any).randomUUID;
+      (crypto as any).randomUUID = undefined;
+      try {
+        const id = generateSubmissionId();
+        expect(id).toMatch(
+          /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+        );
+      } finally {
+        (crypto as any).randomUUID = originalRandomUUID;
+      }
+    });
+  });
+});