@openocean.finance/widget 1.0.0

package/src/stores/form/FormStore.tsx

@@ -0,0 +1,143 @@
+import type { PropsWithChildren } from 'react'
+import { useMemo, useRef } from 'react'
+import { useWidgetConfig } from '../../providers/WidgetProvider/WidgetProvider.js'
+import type { FormRef, ToAddress } from '../../types/widget.js'
+import { HiddenUI } from '../../types/widget.js'
+import { FormStoreContext } from './FormStoreContext.js'
+import { FormUpdater } from './FormUpdater.js'
+import { createFormStore, formDefaultValues } from './createFormStore.js'
+import type { DefaultValues, FormStoreStore } from './types.js'
+import { useFormRef } from './useFormRef.js'
+
+// decorates and initialise the form date for use in the form store
+const initialiseDefaultValues = (
+  defaultValues: Partial<DefaultValues>,
+  fromAmount?: number | string,
+  toAmount?: number | string,
+  toAddress?: ToAddress,
+  hiddenToAddress?: boolean
+) => ({
+  ...formDefaultValues,
+  ...defaultValues,
+  fromAmount:
+    (typeof fromAmount === 'number' ? fromAmount?.toPrecision() : fromAmount) ||
+    formDefaultValues.fromAmount,
+  toAmount:
+    (typeof toAmount === 'number' ? toAmount?.toPrecision() : toAmount) ||
+    formDefaultValues.toAmount,
+  // Prevent setting address when the field is hidden
+  toAddress: hiddenToAddress
+    ? formDefaultValues.toAddress
+    : toAddress?.address || formDefaultValues.toAddress,
+})
+
+interface FormStoreProviderProps extends PropsWithChildren {
+  formRef?: FormRef
+}
+
+export const FormStoreProvider: React.FC<FormStoreProviderProps> = ({
+  children,
+  formRef,
+}) => {
+  const widgetConfig = useWidgetConfig()
+
+  const {
+    fromChain,
+    fromToken,
+    toChain,
+    toToken,
+    fromAmount,
+    toAmount,
+    toAddress,
+    hiddenUI,
+    formUpdateKey,
+  } = widgetConfig
+
+  const storeRef = useRef<FormStoreStore>(null)
+
+  const hiddenToAddress = hiddenUI?.includes(HiddenUI.ToAddress)
+
+  const configHasFromChain = Object.hasOwn(widgetConfig, 'fromChain')
+  const configHasFromToken = Object.hasOwn(widgetConfig, 'fromToken')
+  const configHasFromAmount = Object.hasOwn(widgetConfig, 'fromAmount')
+  const configHasToAmount = Object.hasOwn(widgetConfig, 'toAmount')
+  const configHasToAddress = Object.hasOwn(widgetConfig, 'toAddress')
+  const configHasToChain = Object.hasOwn(widgetConfig, 'toChain')
+  const configHasToToken = Object.hasOwn(widgetConfig, 'toToken')
+
+  // We use the presence/absence of a property to decide if the form values in state need to be updated
+  // We only build and set a property on the memoized form values here if they are included in the
+  // config - undefined is considered a valid value that will reset that form field
+  // biome-ignore lint/correctness/useExhaustiveDependencies: formUpdateKey is needed here.
+  const reactiveFormValues = useMemo(
+    () => ({
+      ...(configHasFromChain ? { fromChain } : undefined),
+      ...(configHasFromToken ? { fromToken } : undefined),
+      ...(configHasFromAmount
+        ? {
+            fromAmount:
+              (typeof fromAmount === 'number'
+                ? fromAmount?.toPrecision()
+                : fromAmount) || formDefaultValues.fromAmount,
+          }
+        : undefined),
+      ...(configHasToAmount
+        ? {
+            toAmount:
+              (typeof toAmount === 'number'
+                ? toAmount?.toPrecision()
+                : toAmount) || formDefaultValues.toAmount,
+          }
+        : undefined),
+      ...(configHasToChain ? { toChain } : undefined),
+      ...(configHasToToken ? { toToken } : undefined),
+      ...(configHasToAddress
+        ? {
+            toAddress: hiddenToAddress
+              ? formDefaultValues.toAddress
+              : toAddress?.address || formDefaultValues.toAddress,
+          }
+        : undefined),
+    }),
+    [
+      fromAmount,
+      toAmount,
+      fromChain,
+      fromToken,
+      hiddenToAddress,
+      toAddress,
+      toChain,
+      toToken,
+      // formUpdateKey should be a randomly assigned unique key. It can be used to force updates for the form field values
+      formUpdateKey,
+      configHasFromChain,
+      configHasFromToken,
+      configHasFromAmount,
+      configHasToAmount,
+      configHasToAddress,
+      configHasToChain,
+      configHasToToken,
+    ]
+  )
+
+  if (!storeRef.current) {
+    storeRef.current = createFormStore(
+      initialiseDefaultValues(
+        reactiveFormValues,
+        fromAmount,
+        toAmount,
+        toAddress,
+        hiddenToAddress
+      )
+    )
+  }
+
+  useFormRef(storeRef.current, formRef)
+
+  return (
+    <FormStoreContext.Provider value={storeRef.current}>
+      {children}
+      <FormUpdater reactiveFormValues={reactiveFormValues} />
+    </FormStoreContext.Provider>
+  )
+}

package/src/stores/form/FormStoreContext.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'react'
+import type { FormStoreStore } from './types.js'
+
+export const FormStoreContext = createContext<FormStoreStore | null>(null)

package/src/stores/form/FormUpdater.tsx

@@ -0,0 +1,92 @@
+import { useAccount } from '@openocean.finance/wallet-management'
+import { useEffect } from 'react'
+import { useChains } from '../../hooks/useChains.js'
+import { useWidgetConfig } from '../../providers/WidgetProvider/WidgetProvider.js'
+import { useBookmarkActions } from '../../stores/bookmarks/useBookmarkActions.js'
+import { formDefaultValues } from '../../stores/form/createFormStore.js'
+import { useSendToWalletActions } from '../../stores/settings/useSendToWalletStore.js'
+import type { DefaultValues } from './types.js'
+import { useFieldActions } from './useFieldActions.js'
+
+export const FormUpdater: React.FC<{
+  reactiveFormValues: Partial<DefaultValues>
+}> = ({ reactiveFormValues }) => {
+  const { fromChain, toChain, toAddress } = useWidgetConfig()
+  const { account } = useAccount()
+  const { chains } = useChains()
+  const { setSendToWallet } = useSendToWalletActions()
+  const { setSelectedBookmark } = useBookmarkActions()
+  const { isTouched, resetField, setFieldValue, setUserAndDefaultValues } =
+    useFieldActions()
+
+  // Set wallet chain as default if no chains are provided by config and if they were not changed during widget usage
+  useEffect(() => {
+    const chainAllowed =
+      account.chainId && chains?.some((chain) => chain.id === account.chainId)
+
+    if (!account.isConnected || !account.chainId || !chainAllowed) {
+      return
+    }
+
+    if (!fromChain && !isTouched('fromChain') && !isTouched('fromToken')) {
+      resetField('fromChain', { defaultValue: account.chainId })
+      setFieldValue('fromToken', '')
+      if (isTouched('fromAmount')) {
+        setFieldValue('fromAmount', '')
+      }
+    }
+    if (!toChain && !isTouched('toChain') && !isTouched('toToken')) {
+      resetField('toChain', { defaultValue: account.chainId })
+      setFieldValue('toToken', '')
+    }
+  }, [
+    account.chainId,
+    account.isConnected,
+    chains,
+    fromChain,
+    toChain,
+    isTouched,
+    resetField,
+    setFieldValue,
+  ])
+
+  // Makes widget config options reactive to changes
+  // should update userValues when defaultValues updates and includes additional logic for chains
+  useEffect(() => {
+    if (reactiveFormValues.toAddress) {
+      setSendToWallet(true)
+    }
+    if (toAddress) {
+      setSelectedBookmark(toAddress)
+    }
+
+    setUserAndDefaultValues(
+      accountForChainId(reactiveFormValues, account.chainId)
+    )
+  }, [
+    account.chainId,
+    toAddress,
+    reactiveFormValues,
+    setUserAndDefaultValues,
+    setSendToWallet,
+    setSelectedBookmark,
+  ])
+
+  return null
+}
+
+const accountForChainId = (
+  defaultValues: Partial<DefaultValues>,
+  chainId?: number
+) => {
+  const result: Partial<DefaultValues> = { ...defaultValues }
+  for (const key in result) {
+    const k = key as keyof DefaultValues
+    if (result[k] === formDefaultValues[k]) {
+      if ((k === 'fromChain' || k === 'toChain') && chainId) {
+        result[k] = chainId
+      }
+    }
+  }
+  return result
+}

package/src/stores/form/URLSearchParamsBuilder.tsx

@@ -0,0 +1,124 @@
+import { useEffect } from 'react'
+import { useLocation } from 'react-router-dom'
+import { useAddressValidation } from '../../hooks/useAddressValidation.js'
+import { useSendToWalletActions } from '../../stores/settings/useSendToWalletStore.js'
+import { formatInputAmount } from '../../utils/format.js'
+import { useBookmarkActions } from '../bookmarks/useBookmarkActions.js'
+import type { DefaultValues, FormFieldNames } from '../form/types.js'
+import { useFieldActions } from '../form/useFieldActions.js'
+import { useFieldValues } from '../form/useFieldValues.js'
+import { useTouchedFields } from '../form/useTouchedFields.js'
+
+const formValueKeys: FormFieldNames[] = [
+  'fromAmount',
+  'fromChain',
+  'fromToken',
+  'toAddress',
+  'toChain',
+  'toToken',
+]
+
+const getDefaultValuesFromQueryString = (): Partial<DefaultValues> => {
+  const searchParams = Object.fromEntries(
+    new URLSearchParams(window?.location.search)
+  )
+
+  // Prevent using fromToken/toToken params if chain is not selected
+  ;['from', 'to'].forEach((key) => {
+    if (searchParams[`${key}Token`] && !searchParams[`${key}Chain`]) {
+      delete searchParams[`${key}Token`]
+    }
+  })
+
+  return {
+    ...(Number.isFinite(Number.parseInt(searchParams.fromChain, 10))
+      ? { fromChain: Number.parseInt(searchParams.fromChain, 10) }
+      : {}),
+    ...(Number.isFinite(Number.parseInt(searchParams.toChain, 10))
+      ? { toChain: Number.parseInt(searchParams.toChain, 10) }
+      : {}),
+    ...(searchParams.fromToken ? { fromToken: searchParams.fromToken } : {}),
+    ...(searchParams.toToken ? { toToken: searchParams.toToken } : {}),
+    ...(Number.isFinite(Number.parseFloat(searchParams.fromAmount))
+      ? { fromAmount: formatInputAmount(searchParams.fromAmount) }
+      : {}),
+    ...(searchParams.toAddress ? { toAddress: searchParams.toAddress } : {}),
+  }
+}
+
+export const URLSearchParamsBuilder = () => {
+  const { pathname } = useLocation()
+  const touchedFields = useTouchedFields()
+  const values = useFieldValues(...formValueKeys)
+  const { setSendToWallet } = useSendToWalletActions()
+  const { setSelectedBookmark, addRecentWallet } = useBookmarkActions()
+  const { validateAddress } = useAddressValidation()
+
+  // Using these methods as trying to use the touchedFields and values above
+  // often has a lag that can effect the widgets initialisation sequence
+  // and accidentally cause values to be wiped from the query string
+  const { getFieldValues, isTouched, setUserAndDefaultValues } =
+    useFieldActions()
+
+  useEffect(() => {
+    // get the initial values from the querystring
+    const formValues = getDefaultValuesFromQueryString()
+
+    /**
+     * When URL builder is enabled and user opens a page with toAddress parameter,
+     * validate the address and set it up as a bookmark. This allows direct linking
+     * to the widget with a pre-filled destination address that will be treated the
+     * same way as a manually entered and validated address.
+     */
+    const initializeFromAddress = async () => {
+      if (formValues.toAddress) {
+        try {
+          const validationResult = await validateAddress({
+            value: formValues.toAddress,
+          })
+          // Check if the toAddress is still in the query string
+          // Could be modified by the user before the validation is done
+          const { toAddress } = getDefaultValuesFromQueryString()
+          if (validationResult.isValid && toAddress) {
+            const bookmark = {
+              address: validationResult.address,
+              chainType: validationResult.chainType,
+            }
+            setSelectedBookmark(bookmark)
+            addRecentWallet(bookmark)
+            setSendToWallet(true)
+          }
+        } catch (_) {
+          // Address validation failed
+        }
+      }
+    }
+
+    initializeFromAddress()
+    setUserAndDefaultValues(formValues)
+  }, [
+    setUserAndDefaultValues,
+    setSendToWallet,
+    validateAddress,
+    setSelectedBookmark,
+    addRecentWallet,
+  ])
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies:
+  useEffect(() => {
+    // set the values on the querysting
+    const url = new URL(window.location as any)
+    formValueKeys.forEach((key, _index) => {
+      const value = getFieldValues(key)[0]
+      if (isTouched(key) && value) {
+        url.searchParams.set(key, value.toString())
+      } else if (url.searchParams.has(key) && !value) {
+        url.searchParams.delete(key)
+      }
+    })
+    url.searchParams.sort()
+    window.history.replaceState(window.history.state, '', url)
+  }, [pathname, touchedFields, values, isTouched, getFieldValues])
+
+  return null
+}

package/src/stores/form/createFormStore.ts

@@ -0,0 +1,234 @@
+import { createWithEqualityFn } from 'zustand/traditional'
+
+import type {
+  DefaultValues,
+  FormFieldArray,
+  FormFieldNames,
+  FormValueControl,
+  FormValues,
+  FormValuesState,
+} from './types.js'
+
+export const formDefaultValues: DefaultValues = {
+  fromAmount: '',
+  toAmount: '',
+  tokenSearchFilter: '',
+}
+
+const defaultValueToFormValue = <T>(value: T): FormValueControl<T> => ({
+  isTouched: false,
+  isDirty: false,
+  value,
+})
+
+const valuesToFormValues = (defaultValues: DefaultValues): FormValues => {
+  return (Object.keys(defaultValues) as FormFieldNames[]).reduce(
+    (accum, key) => {
+      accum[key] = defaultValueToFormValue(defaultValues[key]) as never
+      return accum
+    },
+    {} as FormValues
+  )
+}
+
+const isString = (str: any) => typeof str === 'string' || str instanceof String
+
+const getUpdatedTouchedFields = (userValues: FormValues) => {
+  return (Object.keys(userValues) as FormFieldNames[]).reduce(
+    (accum, key) => {
+      if (userValues[key]?.isTouched) {
+        accum[key] = true
+      }
+      return accum
+    },
+    {} as Record<FormFieldNames, boolean>
+  )
+}
+
+const mergeDefaultFormValues = (
+  userValues: FormValues,
+  defaultValues: FormValues
+) =>
+  (Object.keys(defaultValues) as FormFieldNames[]).reduce<FormValues>(
+    (accum, key) => {
+      const formValue = {
+        isTouched: !!(
+          userValues[key]?.isTouched || defaultValues[key]?.isTouched
+        ),
+        isDirty: !!(userValues[key]?.isDirty || defaultValues[key]?.isTouched),
+        value:
+          userValues[key]?.value || Number.isFinite(userValues[key]?.value)
+            ? userValues[key]?.value
+            : defaultValues[key]?.value,
+      }
+      accum[key] = formValue as never
+      return accum
+    },
+    { ...valuesToFormValues(formDefaultValues) }
+  )
+
+export const createFormStore = (defaultValues?: DefaultValues) =>
+  createWithEqualityFn<FormValuesState>((set, get) => {
+    const _defaultValues = valuesToFormValues({
+      ...formDefaultValues,
+      ...defaultValues,
+    })
+    return {
+      defaultValues: _defaultValues,
+      userValues: _defaultValues,
+      touchedFields: {},
+      isValid: true,
+      isValidating: false,
+      errors: {},
+      validation: {},
+      setDefaultValues: (defaultValue) => {
+        const defaultFormValues = valuesToFormValues(defaultValue)
+        set((state) => ({
+          defaultValues: defaultFormValues,
+          userValues: mergeDefaultFormValues(
+            state.userValues,
+            defaultFormValues
+          ),
+        }))
+      },
+      setUserAndDefaultValues: (formValues) => {
+        const currentUserValues = get().userValues
+        ;(Object.keys(formValues) as FormFieldNames[]).forEach((key) => {
+          if (formValues[key] !== currentUserValues[key]?.value) {
+            get().resetField(key, { defaultValue: formValues[key] })
+            get().setFieldValue(key, formValues[key], { isTouched: true })
+          }
+        })
+      },
+      isTouched: (fieldName: FormFieldNames) =>
+        !!get().userValues[fieldName]?.isTouched,
+      isDirty: (fieldName: FormFieldNames) =>
+        !!get().userValues[fieldName]?.isDirty,
+      setAsTouched: (fieldName: FormFieldNames) => {
+        const userValues = {
+          ...get().userValues,
+          [fieldName]: {
+            ...get().userValues[fieldName],
+            isTouched: true,
+          },
+        }
+
+        const touchedFields = getUpdatedTouchedFields(userValues)
+
+        set(() => ({
+          userValues,
+          touchedFields,
+        }))
+      },
+      resetField: (fieldName, { defaultValue } = {}) => {
+        if (defaultValue) {
+          const fieldValues = {
+            ...get().defaultValues[fieldName],
+            value: defaultValue,
+          }
+          const defaultValues = {
+            ...get().defaultValues,
+            [fieldName]: { ...fieldValues },
+          }
+          const userValues = {
+            ...get().userValues,
+            [fieldName]: { ...fieldValues },
+          }
+          const touchedFields = getUpdatedTouchedFields(userValues)
+
+          set(() => {
+            return {
+              defaultValues,
+              userValues,
+              touchedFields,
+            }
+          })
+        } else {
+          const userValues = {
+            ...get().userValues,
+            [fieldName]: { ...get().defaultValues[fieldName] },
+          }
+          const touchedFields = getUpdatedTouchedFields(userValues)
+
+          set(() => ({
+            userValues,
+            touchedFields,
+          }))
+        }
+      },
+      setFieldValue: (fieldName, value, { isDirty, isTouched } = {}) => {
+        const userValues = {
+          ...get().userValues,
+          [fieldName]: {
+            value,
+            isDirty:
+              isDirty === undefined
+                ? get().userValues[fieldName]?.isDirty
+                : isDirty,
+            isTouched:
+              isTouched === undefined
+                ? get().userValues[fieldName]?.isTouched
+                : isTouched,
+          },
+        }
+
+        const touchedFields = getUpdatedTouchedFields(userValues)
+
+        set(() => ({
+          userValues,
+          touchedFields,
+        }))
+      },
+      getFieldValues: <T extends FormFieldNames[]>(...names: T) =>
+        names.map((name) => get().userValues[name]?.value) as FormFieldArray<T>,
+      addFieldValidation: (name, validationFn) => {
+        set((state) => ({
+          validation: {
+            ...state.validation,
+            [name]: validationFn,
+          },
+        }))
+      },
+      triggerFieldValidation: async (name) => {
+        try {
+          let valid = true
+          set(() => ({ isValid: false, isValidating: true }))
+
+          const validationFn = get().validation[name]
+
+          if (validationFn) {
+            const result = await validationFn(get().userValues?.[name]?.value)
+            if (isString(result)) {
+              valid = false
+              set((state) => ({
+                errors: {
+                  ...state.errors,
+                  [name]: result,
+                },
+              }))
+            } else {
+              valid = result as boolean
+              if (valid) {
+                get().clearErrors(name)
+              }
+            }
+          }
+
+          set(() => ({ isValid: valid, isValidating: false }))
+          return valid
+        } catch (err) {
+          set(() => ({ isValidating: false }))
+          throw err
+        }
+      },
+      clearErrors: (name) => {
+        const newErrors = { ...get().errors }
+
+        delete newErrors[name]
+
+        set(() => ({
+          errors: newErrors,
+        }))
+      },
+    }
+  }, Object.is)

package/src/stores/form/types.ts

@@ -0,0 +1,111 @@
+import type { ContractCall } from '@lifi/sdk'
+import type { StoreApi } from 'zustand'
+import type { UseBoundStoreWithEqualityFn } from 'zustand/traditional'
+
+export interface DefaultFieldValues {
+  fromChain?: number
+  fromToken?: string
+  toChain?: number
+  toToken?: string
+  toAddress?: string
+  fromAmount: string
+  toAmount: string
+}
+
+export interface DefaultValues extends DefaultFieldValues {
+  contractCalls?: ContractCall[]
+  tokenSearchFilter: string
+}
+
+export type GenericFormValue = string | number | ContractCall[] | undefined
+export interface FormValueControl<T> {
+  isTouched: boolean
+  isDirty: boolean
+  value: T
+}
+
+export type FormValues = {
+  [Property in keyof DefaultValues]: FormValueControl<DefaultValues[Property]>
+}
+
+export type FormFieldNames = keyof FormValues
+export type ExtractValueType<T> = T extends FormValueControl<infer U>
+  ? U
+  : never
+export type FormFieldArray<T extends FormFieldNames[]> = {
+  [K in keyof T]: ExtractValueType<FormValues[T[K]]>
+}
+
+export type TouchedFields = { [K in FormFieldNames]?: boolean }
+
+type ValidationFn = (value: any) => Promise<boolean | string>
+export interface ValidationProps {
+  isValid: boolean
+  isValidating: boolean
+  errors: {
+    [K in FormFieldNames]?: string
+  }
+  validation: {
+    [K in FormFieldNames]?: ValidationFn
+  }
+}
+
+export interface ValidationActions {
+  addFieldValidation: (name: FormFieldNames, validationFn: ValidationFn) => void
+  triggerFieldValidation: (name: FormFieldNames) => Promise<boolean>
+  clearErrors: (name: FormFieldNames) => void
+}
+
+export interface FormProps {
+  defaultValues: FormValues
+  userValues: FormValues
+  touchedFields: { [K in FormFieldNames]?: boolean }
+}
+
+export interface ResetOptions {
+  defaultValue?: GenericFormValue
+}
+
+export interface FormActions {
+  setDefaultValues: (formValues: DefaultValues) => void
+  setUserAndDefaultValues: (formValues: Partial<DefaultValues>) => void
+  isTouched: (fieldName: FormFieldNames) => boolean
+  isDirty: (fieldName: FormFieldNames) => boolean
+  setAsTouched: (fieldName: FormFieldNames) => void
+  resetField: (fieldName: FormFieldNames, resetOptions?: ResetOptions) => void
+  setFieldValue: (
+    fieldName: FormFieldNames,
+    value: GenericFormValue,
+    options?: SetOptions
+  ) => void
+  getFieldValues: <T extends FormFieldNames[]>(...names: T) => FormFieldArray<T>
+}
+
+export type FormValuesState = FormProps &
+  FormActions &
+  ValidationProps &
+  ValidationActions
+
+export type FormStoreStore = UseBoundStoreWithEqualityFn<
+  StoreApi<FormValuesState>
+>
+
+export interface SetOptions {
+  isDirty?: boolean
+  isTouched?: boolean
+}
+
+export type FormType = 'from' | 'to'
+
+export interface FormTypeProps {
+  formType: FormType
+}
+
+export const FormKeyHelper = {
+  getChainKey: (formType: FormType): 'fromChain' | 'toChain' =>
+    `${formType}Chain`,
+  getTokenKey: (formType: FormType): 'fromToken' | 'toToken' =>
+    `${formType}Token`,
+  getAmountKey: (formType: FormType): 'fromAmount' | 'toAmount' =>
+    `${formType}Amount`,
+}