@lifi/widget 0.0.0-preview-6cc63bac

package/src/stores/chains/createChainOrderStore.ts

@@ -0,0 +1,128 @@
+import type { StoreApi, UseBoundStore } from 'zustand'
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+import { widgetEvents } from '../../hooks/useWidgetEvents.js'
+import { WidgetEvent } from '../../types/events.js'
+import type { PersistStoreProps } from '../types.js'
+import type { ChainOrderState } from './types.js'
+
+// (10 tiles: 9 + 1 for "All chains")
+export const maxGridItemsToShow = 10
+export const maxChainsToShow: number = maxGridItemsToShow - 1
+// If there are more than maxChainsToShow chains to show,
+// -1 tile to show a button "+ N" more chains
+export const maxChainsToOrder: number = maxChainsToShow - 1
+
+const defaultChainState = {
+  from: [],
+  to: [],
+}
+
+export const createChainOrderStore = ({
+  namePrefix,
+}: PersistStoreProps): UseBoundStore<StoreApi<ChainOrderState>> =>
+  create<ChainOrderState>()(
+    persist(
+      (set, get) => ({
+        chainOrder: defaultChainState,
+        fromIsAllNetworks: true,
+        toIsAllNetworks: true,
+        fromShowAllNetworks: true,
+        toShowAllNetworks: true,
+        availableChains: defaultChainState,
+        pinnedChains: [],
+        initializeChains: (chainIds, type) => {
+          set((state: ChainOrderState) => {
+            const chainOrder = state.chainOrder[type].filter((chainId) =>
+              chainIds.includes(chainId)
+            )
+            const chainsToAdd = chainIds.filter(
+              (chainId) => !chainOrder.includes(chainId)
+            )
+            if (chainOrder.length === maxChainsToOrder || !chainsToAdd.length) {
+              return {
+                availableChains: {
+                  ...state.availableChains,
+                  [type]: chainIds,
+                },
+                chainOrder: {
+                  ...state.chainOrder,
+                  [type]: chainOrder,
+                },
+              }
+            }
+            const chainsToAddLength = maxChainsToOrder - chainOrder.length
+            for (let index = 0; index < chainsToAddLength; index++) {
+              chainOrder.push(chainsToAdd[index])
+            }
+            return {
+              availableChains: {
+                ...state.availableChains,
+                [type]: chainIds,
+              },
+              chainOrder: {
+                ...state.chainOrder,
+                [type]: chainOrder,
+              },
+            }
+          })
+          return get().chainOrder[type].slice(0, maxChainsToOrder)
+        },
+        setChain: (chainId, type) => {
+          const state = get()
+          if (
+            state.chainOrder[type].includes(chainId) ||
+            !state.availableChains[type].includes(chainId)
+          ) {
+            return
+          }
+          set((state: ChainOrderState) => {
+            const chainOrder = [chainId, ...state.chainOrder[type]].slice(
+              0,
+              maxChainsToOrder
+            )
+            return {
+              chainOrder: {
+                ...state.chainOrder,
+                [type]: chainOrder,
+              },
+            }
+          })
+        },
+        setIsAllNetworks: (isAllNetworks, formType) => {
+          set({ [`${formType}IsAllNetworks`]: isAllNetworks })
+        },
+        setShowAllNetworks: (showAllNetworks, formType) => {
+          set({ [`${formType}ShowAllNetworks`]: showAllNetworks })
+        },
+        setPinnedChain: (chainId) => {
+          const currentPinnedChains = get().pinnedChains
+          const wasAlreadyPinned = currentPinnedChains.includes(chainId)
+          set((state: ChainOrderState) => {
+            const pinnedChains = [...state.pinnedChains]
+            if (wasAlreadyPinned) {
+              return {
+                pinnedChains: pinnedChains.filter((id) => id !== chainId),
+              }
+            }
+            pinnedChains.push(chainId)
+            return {
+              pinnedChains,
+            }
+          })
+          widgetEvents.emit(WidgetEvent.ChainPinned, {
+            chainId,
+            pinned: !wasAlreadyPinned,
+          })
+        },
+      }),
+      {
+        name: `${namePrefix || 'li.fi'}-widget-chains-order`,
+        version: 4,
+        partialize: (state) => ({
+          chainOrder: state.chainOrder,
+          pinnedChains: state.pinnedChains,
+        }),
+      }
+    )
+  )

package/src/stores/chains/types.ts

@@ -0,0 +1,25 @@
+import type { FormType } from '../form/types.js'
+
+interface ChainOrderProps {
+  chainOrder: {
+    from: number[]
+    to: number[]
+  }
+  availableChains: {
+    from: number[]
+    to: number[]
+  }
+  fromShowAllNetworks: boolean
+  toShowAllNetworks: boolean
+  fromIsAllNetworks: boolean
+  toIsAllNetworks: boolean
+  pinnedChains: number[]
+}
+
+export interface ChainOrderState extends ChainOrderProps {
+  initializeChains(chainIds: number[], type: FormType): number[]
+  setChain(chainId: number, type: FormType): void
+  setIsAllNetworks(isAllNetworks: boolean, formType: FormType): void
+  setShowAllNetworks(showAllNetworks: boolean, formType: FormType): void
+  setPinnedChain(chainId: number): void
+}

package/src/stores/chains/useChainOrder.ts

@@ -0,0 +1,20 @@
+import { useMemo } from 'react'
+import type { FormType } from '../form/types.js'
+import { useChainOrderStore } from './ChainOrderStore.js'
+import { maxChainsToOrder } from './createChainOrderStore.js'
+
+export const useChainOrder = (
+  type: FormType
+): [number[], (chainId: number, type: FormType) => void] => {
+  const [chainOrder, setChain] = useChainOrderStore((state) => [
+    state.chainOrder[type],
+    state.setChain,
+  ])
+
+  const limitedChainOrder = useMemo(
+    () => chainOrder.slice(0, maxChainsToOrder),
+    [chainOrder]
+  )
+
+  return [limitedChainOrder, setChain]
+}

package/src/stores/form/FormStore.tsx

@@ -0,0 +1,133 @@
+import type { PropsWithChildren } from 'react'
+import { useMemo, useRef } from 'react'
+import { useWidgetConfig } from '../../providers/WidgetProvider/WidgetProvider.js'
+import type { FormRef } from '../../types/widget.js'
+import { createFormStore, formDefaultValues } from './createFormStore.js'
+import { FormStoreContext } from './FormStoreContext.js'
+import { FormUpdater } from './FormUpdater.js'
+import { getDefaultValuesFromQueryString } from './getDefaultValuesFromQueryString.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>) => ({
+  ...formDefaultValues,
+  ...defaultValues,
+  fromAmount:
+    (typeof defaultValues.fromAmount === 'number'
+      ? (defaultValues.fromAmount as number)?.toPrecision?.()
+      : defaultValues.fromAmount) || formDefaultValues.fromAmount,
+  toAmount:
+    (typeof defaultValues.toAmount === 'number'
+      ? (defaultValues.toAmount as number)?.toPrecision?.()
+      : defaultValues.toAmount) || formDefaultValues.toAmount,
+  // Prevent setting address when the field is hidden
+  toAddress: defaultValues.toAddress || 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,
+    formUpdateKey,
+    buildUrl,
+  } = widgetConfig
+
+  const storeRef = useRef<FormStoreStore>(null)
+
+  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: toAddress?.address || formDefaultValues.toAddress,
+          }
+        : undefined),
+    }),
+    [
+      fromAmount,
+      toAmount,
+      fromChain,
+      fromToken,
+      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) {
+    const queryDefaults = getDefaultValuesFromQueryString({
+      buildUrl,
+      includeToAddress: false,
+    })
+    storeRef.current = createFormStore(
+      initialiseDefaultValues({
+        ...reactiveFormValues,
+        ...queryDefaults,
+      })
+    )
+  }
+
+  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,5 @@
+import { type Context, createContext } from 'react'
+import type { FormStoreStore } from './types.js'
+
+export const FormStoreContext: Context<FormStoreStore | null> =
+  createContext<FormStoreStore | null>(null)

package/src/stores/form/FormUpdater.tsx

@@ -0,0 +1,52 @@
+import { useAccount } from '@lifi/wallet-management'
+import { useEffect } from 'react'
+import { useWidgetConfig } from '../../providers/WidgetProvider/WidgetProvider.js'
+import { useBookmarkActions } from '../../stores/bookmarks/useBookmarkActions.js'
+import { formDefaultValues } from '../../stores/form/createFormStore.js'
+import type { DefaultValues } from './types.js'
+import { useFieldActions } from './useFieldActions.js'
+
+export const FormUpdater: React.FC<{
+  reactiveFormValues: Partial<DefaultValues>
+}> = ({ reactiveFormValues }) => {
+  const { toAddress } = useWidgetConfig()
+  const { account } = useAccount()
+  const { setSelectedBookmark } = useBookmarkActions()
+  const { setUserAndDefaultValues } = useFieldActions()
+
+  // React to changes in widget config options (reactiveFormValues), updating userValues accordingly.
+  // Includes special logic for chain fields, where account.chainId is only a fallback and not a direct reactivity source.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: account.chainId is used as a fallback only and does not need to be a dependency for reactivity.
+  useEffect(() => {
+    if (toAddress) {
+      setSelectedBookmark(toAddress)
+    }
+
+    setUserAndDefaultValues(
+      accountForChainId(reactiveFormValues, account.chainId)
+    )
+  }, [
+    toAddress,
+    reactiveFormValues,
+    setUserAndDefaultValues,
+    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,93 @@
+import { useLocation } from '@tanstack/react-router'
+import { useEffect } from 'react'
+import { useAddressValidation } from '../../hooks/useAddressValidation.js'
+import { useWidgetConfig } from '../../providers/WidgetProvider/WidgetProvider.js'
+import { useBookmarkActions } from '../bookmarks/useBookmarkActions.js'
+import type { FormFieldNames } from '../form/types.js'
+import { useFieldActions } from '../form/useFieldActions.js'
+import { useFieldValues } from '../form/useFieldValues.js'
+import { useTouchedFields } from '../form/useTouchedFields.js'
+import { getDefaultValuesFromQueryString } from './getDefaultValuesFromQueryString.js'
+
+const formValueKeys: FormFieldNames[] = [
+  'fromAmount',
+  'fromChain',
+  'fromToken',
+  'toAddress',
+  'toChain',
+  'toToken',
+]
+
+export const URLSearchParamsBuilder = () => {
+  const { pathname } = useLocation()
+  const touchedFields = useTouchedFields()
+  const values = useFieldValues(...formValueKeys)
+  const { setSelectedBookmark, addRecentWallet } = useBookmarkActions()
+  const { validateAddress } = useAddressValidation()
+  const { buildUrl } = useWidgetConfig()
+  // 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({ buildUrl })
+    const { toAddress, ...initialFormValues } = formValues
+
+    /**
+     * 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 (toAddress) {
+        try {
+          const validationResult = await validateAddress({
+            value: toAddress,
+          })
+          if (validationResult.isValid && toAddress) {
+            const bookmark = {
+              address: validationResult.address,
+              chainType: validationResult.chainType,
+            }
+            setUserAndDefaultValues({ toAddress })
+            setSelectedBookmark(bookmark)
+            addRecentWallet(bookmark)
+          }
+        } catch (_) {
+          // Address validation failed
+        }
+      }
+    }
+
+    setUserAndDefaultValues(initialFormValues)
+    initializeFromAddress()
+  }, [
+    setUserAndDefaultValues,
+    validateAddress,
+    setSelectedBookmark,
+    addRecentWallet,
+    buildUrl,
+  ])
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: run only when pathname changes
+  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,237 @@
+import type { StoreApi, UseBoundStore } from 'zustand'
+import { create } from 'zustand'
+
+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
+): UseBoundStore<StoreApi<FormValuesState>> =>
+  create<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,
+        }))
+      },
+    }
+  })