@elliemae/loan-field-renderers 26.2.2

package/dist/esm/renderer/field-renderers/ZipCodeRenderer/helper.js

@@ -0,0 +1,112 @@
+import { useCallback, useEffect, useRef } from "react";
+const useDebouncedCallback = (callback, waitTimeout = 150, options = { leading: false }) => {
+  const timeoutRef = useRef(null);
+  const leadingRef = useRef(options.leading ?? false);
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  const clearTimeoutFn = useCallback(() => {
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+  useEffect(() => clearTimeoutFn, [clearTimeoutFn]);
+  const debouncedCallback = useCallback(
+    (...args) => {
+      clearTimeoutFn();
+      if (leadingRef.current) {
+        callbackRef.current(...args);
+        leadingRef.current = false;
+      } else {
+        timeoutRef.current = window.setTimeout(() => {
+          callbackRef.current(...args);
+          leadingRef.current = options.leading ?? false;
+        }, waitTimeout);
+      }
+    },
+    [waitTimeout, clearTimeoutFn, options.leading]
+  );
+  return debouncedCallback;
+};
+class ZipCodeHelper {
+  // Prevent instantiation - this is a static utility class
+  constructor() {
+  }
+  static SECTION_OPTION = {
+    dsId: "section",
+    type: "section",
+    label: "Please select the appropriate city",
+    options: [],
+    zipNumber: "",
+    cityData: null
+  };
+  static DEFAULT_COUNTRY_CODE = "US";
+  /**
+   * Normalizes city data from various API response formats
+   * Handles both uppercase and lowercase property names
+   * @param cityData - The city data object to normalize
+   * @returns Normalized object with lowercase property names
+   */
+  static normalizeCityData(cityData) {
+    return {
+      city: cityData?.City ?? cityData?.city ?? "",
+      state: cityData?.State ?? cityData?.state ?? "",
+      county: cityData?.County ?? cityData?.county ?? ""
+    };
+  }
+  /**
+   * Formats a city data option into a readable label
+   * Format: "City - County - State"
+   * @param option - The city data to format
+   * @returns Formatted string label
+   */
+  static formatOptionLabel(option) {
+    return [
+      option.City ?? option.city ?? "",
+      option.County ?? option.county ?? "",
+      option.State ?? option.state ?? ""
+    ].filter(Boolean).join(" - ");
+  }
+  /**
+   * Builds autocomplete options from zip code lookup data
+   * When multiple cities exist for a zip code, adds a section header
+   * @param zip - The zip code string
+   * @param data - Array of city data for the zip code
+   * @returns Array of autocomplete options
+   */
+  static buildOptions(zip, data) {
+    const optionEntries = data.map((option, index) => ({
+      dsId: `${index}`,
+      type: "option",
+      label: this.formatOptionLabel(option),
+      value: zip,
+      zipNumber: zip,
+      cityData: option
+    }));
+    if (optionEntries.length <= 1) {
+      return optionEntries;
+    }
+    return [
+      { ...this.SECTION_OPTION, zipNumber: zip, options: optionEntries },
+      ...optionEntries
+    ];
+  }
+  /**
+   * Validates whether any geo fields contain non-empty address data
+   * @param geoFields - Optional geo fields object to validate
+   * @returns True if any geo field has non-empty string value
+   */
+  static hasAddressTargets(geoFields) {
+    return Boolean(
+      geoFields && Object.values(geoFields).some(
+        (value) => typeof value === "string" && value.length
+      )
+    );
+  }
+}
+export {
+  ZipCodeHelper,
+  useDebouncedCallback
+};

package/dist/esm/renderer/field-renderers/ZipCodeRenderer/hook.js

@@ -0,0 +1,108 @@
+import { useCallback, useMemo, useState } from "react";
+import { ZipCodeHelper, useDebouncedCallback } from "./helper";
+const useZipCodeLookup = ({
+  ssf,
+  onGeoLookupComplete,
+  useLatLong,
+  isForeignAddress,
+  geoFields
+}) => {
+  const [options, setOptions] = useState([]);
+  const shouldAutoFill = useMemo(
+    () => ZipCodeHelper.hasAddressTargets(geoFields),
+    [geoFields]
+  );
+  const applyAddressData = useCallback(
+    async (zipNumber, cityData) => {
+      if (!cityData) return;
+      onGeoLookupComplete?.(zipNumber, cityData);
+      if (!shouldAutoFill || !geoFields) return;
+      const { city, state, county, country, zip } = geoFields;
+      const normalized = ZipCodeHelper.normalizeCityData(cityData);
+      const payload = {};
+      const fieldMappings = [
+        [zip, zipNumber],
+        [city, normalized.city],
+        [state, normalized.state],
+        [county, normalized.county]
+      ];
+      fieldMappings.forEach(([fieldKey, value]) => {
+        if (fieldKey && value) {
+          payload[fieldKey] = value;
+        }
+      });
+      if (country && !isForeignAddress) {
+        payload[country] = ZipCodeHelper.DEFAULT_COUNTRY_CODE;
+      }
+      if (Object.keys(payload).length) {
+        try {
+          await ssf.setFieldsValues(payload, true);
+        } catch (error) {
+        }
+      }
+    },
+    [geoFields, isForeignAddress, shouldAutoFill, ssf, onGeoLookupComplete]
+  );
+  const fetchZipResults = useCallback(
+    async (zip) => {
+      const rawResults = useLatLong ? await ssf.getZipCodeOptionsWithLatLong(zip) : await ssf.getZipCodeOptions(zip);
+      return Array.isArray(rawResults) ? rawResults : [];
+    },
+    [ssf, useLatLong]
+  );
+  const handleLookupResults = useCallback(
+    async (zip, results) => {
+      if (results.length === 1) {
+        setOptions([]);
+        await applyAddressData(zip, results[0]);
+      } else if (results.length > 1) {
+        setOptions(ZipCodeHelper.buildOptions(zip, results));
+      } else {
+        setOptions([]);
+      }
+    },
+    [applyAddressData]
+  );
+  const runLookup = useCallback(
+    async (zip) => {
+      if (!zip || isForeignAddress) {
+        setOptions([]);
+        return;
+      }
+      try {
+        const results = await fetchZipResults(zip);
+        await handleLookupResults(zip, results);
+      } catch (error) {
+        setOptions([]);
+      }
+    },
+    [fetchZipResults, handleLookupResults, isForeignAddress]
+  );
+  const clearOptions = useCallback(() => setOptions([]), []);
+  const debouncedLookup = useDebouncedCallback((zip) => {
+    runLookup(zip);
+  });
+  const handleOptionSelect = useCallback(
+    (label) => {
+      if (!label) return null;
+      const match = options.find(
+        (item) => item.type === "option" && item.label === label
+      );
+      if (!match) return null;
+      clearOptions();
+      applyAddressData(match.zipNumber, match.cityData).catch(() => {
+      });
+      return match;
+    },
+    [applyAddressData, clearOptions, options]
+  );
+  return {
+    options,
+    searchZipCode: debouncedLookup,
+    handleOptionSelect,
+    clearOptions
+  };
+};
+export {
+  useZipCodeLookup
+};

package/dist/esm/renderer/field-renderers/ZipCodeRenderer/index.js

@@ -0,0 +1,247 @@
+import { jsx } from "react/jsx-runtime";
+import React, { useCallback } from "react";
+import {
+  useZipCodeMask,
+  DSAutocomplete,
+  DSInputText
+} from "@elliemae/ds-controlled-form";
+import { Renderer } from "../../base/renderer";
+import { AddonRenderer } from "../AddonRenderer";
+import { useZipCodeLookup } from "./hook";
+class ZipCodeRenderer extends Renderer {
+  AddOnRenderer;
+  constructor() {
+    super();
+    this.AddOnRenderer = new AddonRenderer().render();
+    this.BRWrapper = this.renderBR();
+  }
+  render() {
+    const ZipComponent = (props) => {
+      const {
+        id,
+        fieldId,
+        isDisable,
+        validationRules = [],
+        onChange,
+        onBlur,
+        label,
+        rightAddon,
+        isForeignAddress = false,
+        useLatLong = false,
+        onGeoLookupComplete,
+        geoFields,
+        brCompProps,
+        ...rest
+      } = props;
+      const { BRWrapper, AddOnRenderer } = this;
+      const {
+        fieldMetadata: {
+          isLockField = false,
+          maxLength = 0,
+          fieldFormat = ""
+        } = {},
+        fieldValue,
+        setFieldValue,
+        isLockedState,
+        isSearchedField,
+        setIsSearchedField,
+        isFieldDisabled,
+        validationResult,
+        ariaDescProps
+      } = this.initVM(props);
+      this.fieldFormat = fieldFormat;
+      const { options, searchZipCode, handleOptionSelect, clearOptions } = useZipCodeLookup({
+        ssf: this.BLL.SSF,
+        onGeoLookupComplete,
+        useLatLong,
+        isForeignAddress,
+        geoFields: { ...geoFields, zip: fieldId }
+      });
+      const zipCodeInputProps = useZipCodeMask({
+        valueSetter: (value) => {
+          if (!isDisable && !isFieldDisabled && !isForeignAddress) {
+            setFieldValue(value);
+          }
+        }
+      });
+      const handleForeignAddressChange = useCallback(
+        (newValue) => {
+          setFieldValue(newValue);
+          if (onChange) {
+            onChange(fieldId, newValue);
+          }
+        },
+        [fieldId, onChange, setFieldValue]
+      );
+      const handleUSZipChange = useCallback(
+        (newValue) => {
+          if (!newValue) {
+            setFieldValue("");
+            clearOptions();
+            if (onChange) {
+              onChange(fieldId, "");
+            }
+            return;
+          }
+          if (!/\d/.test(newValue)) {
+            return;
+          }
+          const formattedValue = this.getFormattedValue(newValue);
+          setFieldValue(formattedValue);
+          const parsedValue = this.getParsedValue(formattedValue);
+          if (onChange) {
+            onChange(fieldId, parsedValue);
+          }
+          const { isValid } = this.BLL.Validator.createValidator("zip").validate(formattedValue);
+          if (isValid) {
+            searchZipCode(formattedValue);
+          } else {
+            clearOptions();
+          }
+        },
+        [fieldId, onChange, setFieldValue, clearOptions, searchZipCode]
+      );
+      const onChangeEvent = useCallback(
+        (newValue) => {
+          setIsSearchedField(false);
+          if (isDisable || isFieldDisabled) return;
+          if (isForeignAddress) {
+            handleForeignAddressChange(newValue);
+          } else {
+            handleUSZipChange(newValue);
+          }
+        },
+        [
+          isForeignAddress,
+          isDisable,
+          isFieldDisabled,
+          setIsSearchedField,
+          handleForeignAddressChange,
+          handleUSZipChange
+        ]
+      );
+      const onAutocompleteSelect = useCallback(
+        (selectedLabel) => {
+          if (isForeignAddress || isDisable || isFieldDisabled) return;
+          const selectedOption = handleOptionSelect(selectedLabel);
+          if (!selectedOption) return;
+          const formattedValue = this.getFormattedValue(
+            selectedOption.zipNumber
+          );
+          setFieldValue(formattedValue);
+          const parsedValue = this.getParsedValue(formattedValue);
+          if (onChange) {
+            onChange(fieldId, parsedValue);
+          }
+        },
+        [
+          fieldId,
+          handleOptionSelect,
+          isForeignAddress,
+          isDisable,
+          isFieldDisabled,
+          onChange,
+          setFieldValue
+        ]
+      );
+      const onBlurEvent = useCallback(
+        (e) => {
+          const { value } = e.target;
+          if (isDisable || isFieldDisabled) return;
+          const formattedValue = isForeignAddress ? value : this.getFormattedValue(value);
+          setFieldValue(formattedValue);
+          const rulesToCheck = [...validationRules];
+          const tempValResult = this.Hooks.runValidationsOnValue(
+            formattedValue,
+            rulesToCheck
+          );
+          this.VM.setValidationResult(tempValResult);
+          if (!tempValResult.isValid) {
+            return;
+          }
+          const parsedValue = isForeignAddress ? formattedValue : this.getParsedValue(formattedValue);
+          (async () => {
+            await this.BLL.SSF.setFieldValue(fieldId, parsedValue);
+          })();
+          if (onBlur) {
+            onBlur(fieldId, parsedValue);
+          }
+        },
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [fieldId, isForeignAddress, isDisable, onBlur, validationRules]
+      );
+      const validationProps = this.buildValidationProps(validationResult);
+      return /* @__PURE__ */ jsx(
+        BRWrapper,
+        {
+          fieldId,
+          inputID: fieldId,
+          label,
+          value: fieldValue || "",
+          ...validationProps,
+          ...brCompProps || {},
+          withHighlight: isSearchedField,
+          children: /* @__PURE__ */ jsx(
+            AddOnRenderer,
+            {
+              rendererType: "addon",
+              fieldId,
+              isLocked: isLockedState,
+              isPadLock: isLockField,
+              isDisable,
+              rightAddon,
+              onPadLockToggle: () => this.toggleLockStatus(fieldId, isLockedState || false),
+              children: isForeignAddress ? /* @__PURE__ */ jsx(
+                DSInputText,
+                {
+                  id,
+                  "data-testid": fieldId,
+                  value: fieldValue || "",
+                  onValueChange: onChangeEvent,
+                  onBlur: onBlurEvent,
+                  disabled: isFieldDisabled || isDisable,
+                  applyAriaDisabled: isFieldDisabled || isDisable,
+                  ...maxLength && maxLength > 0 && { maxLength },
+                  ...ariaDescProps,
+                  ...this.sanitize(rest)
+                }
+              ) : /* @__PURE__ */ jsx(
+                DSAutocomplete,
+                {
+                  placeholder: "",
+                  options,
+                  filter: fieldValue || "",
+                  onSelect: onAutocompleteSelect,
+                  disabled: isFieldDisabled || isDisable,
+                  children: /* @__PURE__ */ jsx(
+                    DSInputText,
+                    {
+                      id,
+                      "data-testid": fieldId,
+                      value: fieldValue || "",
+                      autoComplete: "off",
+                      onValueChange: onChangeEvent,
+                      onBlur: onBlurEvent,
+                      disabled: isFieldDisabled || isDisable,
+                      applyAriaDisabled: isFieldDisabled || isDisable,
+                      ...maxLength && maxLength > 0 && { maxLength },
+                      ...zipCodeInputProps,
+                      ...ariaDescProps,
+                      ...this.sanitize(rest)
+                    }
+                  )
+                }
+              )
+            }
+          )
+        }
+      );
+    };
+    return React.memo(ZipComponent);
+  }
+}
+var ZipCodeRenderer_default = ZipCodeRenderer;
+export {
+  ZipCodeRenderer,
+  ZipCodeRenderer_default as default
+};

package/dist/esm/renderer/index.js

@@ -0,0 +1,4 @@
+import { FieldRenderer } from "./FieldRenderer";
+export {
+  FieldRenderer
+};

package/dist/esm/renderer/styles.js

@@ -0,0 +1,21 @@
+import styled from "styled-components";
+import { getDefaultTheme } from "@elliemae/pui-theme";
+import { DSControlledDateTimePicker } from "@elliemae/ds-form-date-time-picker";
+const EmptyLabel = styled.label`
+  display: block;
+  height: 1rem;
+  line-height: 1.15rem;
+`;
+const StyledDateTimePicker = styled(DSControlledDateTimePicker)`
+  width: auto;
+
+  & div:last-child {
+    justify-content: end;
+  }
+`;
+const theme = getDefaultTheme();
+export {
+  EmptyLabel,
+  StyledDateTimePicker,
+  theme
+};

package/dist/esm/tests/base/flowBase.js

@@ -0,0 +1,105 @@
+class FlowBase {
+  constructor(flowParams) {
+    this.flowParams = flowParams;
+  }
+  flowParams;
+  setTimeoutAwaitable(timeout = 100) {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        resolve();
+      }, timeout);
+    });
+  }
+  getFlowName(rendererName, description) {
+    return `component: ${rendererName} - ${description}`;
+  }
+  static get Mocks() {
+    return {
+      apis: [],
+      ssf: {
+        loconnect: {
+          getStateDropDownList: [
+            { name: "Alabama", value: "AL" },
+            { name: "California", value: "CA" },
+            { name: "New York", value: "NY" },
+            { name: "Texas", value: "TX" }
+          ],
+          // Zip code lookup - single result (auto-fill)
+          getZipCodeData: (zip) => {
+            if (zip === "90210") {
+              return [
+                { City: "Beverly Hills", State: "CA", County: "Los Angeles" }
+              ];
+            }
+            if (zip === "10001") {
+              return [
+                { City: "New York", State: "NY", County: "New York" },
+                { City: "Manhattan", State: "NY", County: "New York" }
+              ];
+            }
+            if (zip === "94105") {
+              return [
+                {
+                  City: "San Francisco",
+                  State: "CA",
+                  County: "San Francisco"
+                }
+              ];
+            }
+            if (zip === "75001") {
+              return [{ City: "Addison", State: "TX", County: "Dallas" }];
+            }
+            return [];
+          },
+          // Zip code lookup with lat/long
+          getZipCodeLatLong: (zip) => {
+            if (zip === "90210") {
+              return [
+                {
+                  city: "Beverly Hills",
+                  state: "CA",
+                  county: "Los Angeles",
+                  latitude: "34.0901",
+                  longitude: "-118.4065"
+                }
+              ];
+            }
+            if (zip === "10001") {
+              return [
+                {
+                  city: "New York",
+                  state: "NY",
+                  county: "New York",
+                  latitude: "40.7484",
+                  longitude: "-73.9967"
+                },
+                {
+                  city: "Manhattan",
+                  state: "NY",
+                  county: "New York",
+                  latitude: "40.7831",
+                  longitude: "-73.9712"
+                }
+              ];
+            }
+            if (zip === "94105") {
+              return [
+                {
+                  city: "San Francisco",
+                  state: "CA",
+                  county: "San Francisco",
+                  latitude: "37.7893",
+                  longitude: "-122.3959"
+                }
+              ];
+            }
+            return [];
+          }
+        }
+      }
+    };
+  }
+}
+export {
+  FlowBase
+};

package/dist/esm/tests/base/index.js

@@ -0,0 +1,22 @@
+import React from "react";
+import { render } from "@testing-library/react";
+import { ThemeProvider } from "styled-components";
+import { getDefaultTheme } from "@elliemae/pui-theme";
+import { FlowRunner } from "@elliemae/flow-driven-testing";
+import { Demo } from "../../demo";
+class TestBase extends FlowRunner {
+  mountApp() {
+    return render(
+      React.createElement(
+        ThemeProvider,
+        { theme: getDefaultTheme() },
+        React.createElement(Demo)
+      )
+    );
+  }
+  init() {
+  }
+}
+export {
+  TestBase
+};

package/dist/esm/tests/flows/checkboxRendererFlows.js

@@ -0,0 +1,65 @@
+import { TTriggerActions } from "@elliemae/flow-driven-testing";
+import { FlowBase } from "../base/flowBase";
+class CheckboxRendererFlows extends FlowBase {
+  constructor(flowParams) {
+    super(flowParams);
+    this.flowParams = flowParams;
+  }
+  flowParams;
+  UpdateCheckboxStatus() {
+    return {
+      [`${this.flowParams.inboundFlow}`]: {
+        name: this.getFlowName("CheckboxRenderer", "update checkbox status"),
+        startFlow: [
+          {
+            selector: '[data-testid="LE1.X78"]',
+            action: TTriggerActions.CLICK
+          }
+        ],
+        asserts: [
+          {
+            ssfFunctionsCalled: ["setFields"]
+          }
+        ],
+        transitions: [
+          {
+            to: "checkCheckboxDisabled"
+          }
+        ]
+      }
+    };
+  }
+  CheckCheckboxDisabled() {
+    return {
+      checkCheckboxDisabled: {
+        name: this.getFlowName("CheckboxRenderer", "check checkbox disabled"),
+        startFlow: [
+          {
+            selector: '[data-testid="LE1.X78"]',
+            action: TTriggerActions.CLICK
+          }
+        ],
+        asserts: [
+          {
+            selector: '[data-testid="LE1.X79"]',
+            isEnabled: false
+          }
+        ],
+        transitions: [
+          {
+            to: this.flowParams.outboundFlow || ""
+          }
+        ]
+      }
+    };
+  }
+  get Flows() {
+    return {
+      ...this.UpdateCheckboxStatus(),
+      ...this.CheckCheckboxDisabled()
+    };
+  }
+}
+export {
+  CheckboxRendererFlows
+};