refactor: connect method and wallet features for customization and so…

…rting features (#3400)

.changeset/old-laws-brake.md

@@ -0,0 +1,21 @@
+---
+'@reown/appkit-scaffold-ui': patch
+'@reown/appkit': patch
+'@reown/appkit-core': patch
+'@reown/appkit-adapter-ethers': patch
+'@reown/appkit-adapter-ethers5': patch
+'@reown/appkit-adapter-solana': patch
+'@reown/appkit-adapter-wagmi': patch
+'@reown/appkit-utils': patch
+'@reown/appkit-cdn': patch
+'appkit-cli': patch
+'@reown/appkit-common': patch
+'@reown/appkit-experimental': patch
+'@reown/appkit-polyfills': patch
+'@reown/appkit-siwe': patch
+'@reown/appkit-siwx': patch
+'@reown/appkit-ui': patch
+'@reown/appkit-wallet': patch
+---
+
+Refactors some ui rendering logics and enables setting extra configurations via modal functions

packages/appkit/src/client.ts

@@ -20,8 +20,13 @@ import {
   type EstimateGasTransactionArgs,
   type AccountControllerState,
   type AdapterNetworkState,
+  type Features,
   SIWXUtil,
-  type ConnectionStatus
+  type ConnectionStatus,
+  type OptionsControllerState,
+  type WalletFeature,
+  type ConnectMethod,
+  type SocialProvider
 } from '@reown/appkit-core'
 import {
   AccountController,
@@ -294,6 +299,14 @@ export class AppKit {
     setColorTheme(ThemeController.state.themeMode)
   }
 
+  public setTermsConditionsUrl(termsConditionsUrl: string) {
+    OptionsController.setTermsConditionsUrl(termsConditionsUrl)
+  }
+
+  public setPrivacyPolicyUrl(privacyPolicyUrl: string) {
+    OptionsController.setPrivacyPolicyUrl(privacyPolicyUrl)
+  }
+
   public setThemeVariables(themeVariables: ThemeControllerState['themeVariables']) {
     ThemeController.setThemeVariables(themeVariables)
     setThemeVariables(ThemeController.state.themeVariables)
@@ -597,6 +610,32 @@ export class AppKit {
     }
   }
 
+  public updateFeatures(newFeatures: Partial<Features>) {
+    OptionsController.setFeatures(newFeatures)
+  }
+
+  public updateOptions(newOptions: Partial<OptionsControllerState>) {
+    const currentOptions = OptionsController.state || {}
+    const updatedOptions = { ...currentOptions, ...newOptions }
+    OptionsController.setOptions(updatedOptions)
+  }
+
+  public setConnectMethodsOrder(connectMethodsOrder: ConnectMethod[]) {
+    OptionsController.setConnectMethodsOrder(connectMethodsOrder)
+  }
+
+  public setWalletFeaturesOrder(walletFeaturesOrder: WalletFeature[]) {
+    OptionsController.setWalletFeaturesOrder(walletFeaturesOrder)
+  }
+
+  public setCollapseWallets(collapseWallets: boolean) {
+    OptionsController.setCollapseWallets(collapseWallets)
+  }
+
+  public setSocialsOrder(socialsOrder: SocialProvider[]) {
+    OptionsController.setSocialsOrder(socialsOrder)
+  }
+
   public async disconnect() {
     await this.connectionControllerClient?.disconnect()
   }
@@ -612,6 +651,7 @@ export class AppKit {
     OptionsController.setDebug(options.debug)
     OptionsController.setProjectId(options.projectId)
     OptionsController.setSdkVersion(options.sdkVersion)
+    OptionsController.setEnableEmbedded(options.enableEmbedded)
 
     if (!options.projectId) {
       AlertController.open(ErrorUtil.ALERT_ERRORS.PROJECT_ID_NOT_CONFIGURED, 'error')

packages/core/src/controllers/ModalController.ts

@@ -7,6 +7,7 @@ import type { RouterControllerState } from './RouterController.js'
 import { RouterController } from './RouterController.js'
 import { ChainController } from './ChainController.js'
 import { CoreHelperUtil } from '../utils/CoreHelperUtil.js'
+import { OptionsController } from './OptionsController.js'
 
 // -- Types --------------------------------------------- //
 export interface ModalControllerState {
@@ -67,9 +68,21 @@ export const ModalController = {
   },
 
   close() {
+    const isEmbeddedEnabled = OptionsController.state.enableEmbedded
     const connected = Boolean(ChainController.state.activeCaipAddress)
+
     state.open = false
-    PublicStateController.set({ open: false })
+
+    if (isEmbeddedEnabled) {
+      if (connected) {
+        RouterController.replace('Account')
+      } else {
+        RouterController.push('Connect')
+      }
+    } else {
+      PublicStateController.set({ open: false })
+    }
+
     EventsController.sendEvent({
       type: 'track',
       event: 'MODAL_CLOSE',

packages/core/src/controllers/OptionsController.ts

@@ -1,12 +1,15 @@
 import { subscribeKey as subKey } from 'valtio/vanilla/utils'
 import { proxy } from 'valtio/vanilla'
 import type {
+  ConnectMethod,
   CustomWallet,
   Features,
   Metadata,
   ProjectId,
   SdkVersion,
-  Tokens
+  SocialProvider,
+  Tokens,
+  WalletFeature
 } from '../utils/TypeUtil.js'
 import { ConstantsUtil } from '../utils/ConstantsUtil.js'
 import type { SIWXConfig } from '../utils/SIWXUtil.js'
@@ -117,6 +120,11 @@ export interface OptionsControllerStatePublic {
    * @default undefined
    */
   siwx?: SIWXConfig
+  /**
+   * Renders the AppKit to DOM instead of the default modal.
+   * @default false
+   */
+  enableEmbedded?: boolean
 }
 
 export interface OptionsControllerStateInternal {
@@ -155,15 +163,14 @@ export const OptionsController = {
       return
     }
 
-    Object.entries(features).forEach(([key, value]) => {
-      if (!state.features) {
-        state.features = ConstantsUtil.DEFAULT_FEATURES
-      }
+    if (!state.features) {
+      state.features = ConstantsUtil.DEFAULT_FEATURES
+
+      return
+    }
 
-      if (key in state.features) {
-        ;(state.features as Record<keyof Features, unknown>)[key as keyof Features] = value
-      }
-    })
+    const newFeatures = { ...state.features, ...features }
+    state.features = newFeatures
   },
 
   setProjectId(projectId: OptionsControllerState['projectId']) {
@@ -244,5 +251,37 @@ export const OptionsController = {
 
   setSIWX(siwx: OptionsControllerState['siwx']) {
     state.siwx = siwx
+  },
+
+  setConnectMethodsOrder(connectMethodsOrder: ConnectMethod[]) {
+    state.features = {
+      ...state.features,
+      connectMethodsOrder
+    }
+  },
+
+  setWalletFeaturesOrder(walletFeaturesOrder: WalletFeature[]) {
+    state.features = {
+      ...state.features,
+      walletFeaturesOrder
+    }
+  },
+
+  setSocialsOrder(socialsOrder: SocialProvider[]) {
+    state.features = {
+      ...state.features,
+      socials: socialsOrder
+    }
+  },
+
+  setCollapseWallets(collapseWallets: boolean) {
+    state.features = {
+      ...state.features,
+      collapseWallets
+    }
+  },
+
+  setEnableEmbedded(enableEmbedded: OptionsControllerState['enableEmbedded']) {
+    state.enableEmbedded = enableEmbedded
   }
 }

packages/core/src/utils/ConstantsUtil.ts

@@ -1,4 +1,4 @@
-import type { Features } from './TypeUtil.js'
+import type { Features, SocialProvider } from './TypeUtil.js'
 import type { ChainNamespace } from '@reown/appkit-common'
 
 const SECURE_SITE = 'https://secure.walletconnect.org'
@@ -217,13 +217,26 @@ export const ConstantsUtil = {
   DEFAULT_FEATURES: {
     swaps: true,
     onramp: true,
+    receive: true,
+    send: true,
     email: true,
     emailShowWallets: true,
-    socials: ['google', 'x', 'discord', 'farcaster', 'github', 'apple', 'facebook'],
+    socials: [
+      'google',
+      'x',
+      'discord',
+      'farcaster',
+      'github',
+      'apple',
+      'facebook'
+    ] as SocialProvider[],
     history: true,
     analytics: true,
     allWallets: true,
     legalCheckbox: false,
-    smartSessions: false
-  } as Features
+    smartSessions: false,
+    collapseWallets: false,
+    connectMethodsOrder: ['email', 'social', 'wallet'],
+    walletFeaturesOrder: ['onramp', 'swaps', 'receive', 'send']
+  } satisfies Features
 }

packages/core/src/utils/TypeUtil.ts

@@ -982,14 +982,9 @@ export type CombinedProvider = W3mFrameProvider & Provider
 export type CoinbasePaySDKChainNameValues =
   keyof typeof ConstantsUtil.WC_COINBASE_PAY_SDK_CHAIN_NAME_MAP
 
-export type FeaturesSocials =
-  | 'google'
-  | 'x'
-  | 'discord'
-  | 'farcaster'
-  | 'github'
-  | 'apple'
-  | 'facebook'
+export type WalletFeature = 'swaps' | 'send' | 'receive' | 'onramp'
+
+export type ConnectMethod = 'email' | 'social' | 'wallet'
 
 export type Features = {
   /**
@@ -1002,21 +997,33 @@ export type Features = {
    * @type {boolean}
    */
   onramp?: boolean
+  /**
+   * @description Enable or disable the receive feature. Enabled by default.
+   * This feature is only visible when connected with email/social. It's not possible to configure when connected with wallet, which is enabled by default.
+   * @type {boolean}
+   */
+  receive?: boolean
+  /**
+   * @description Enable or disable the send feature. Enabled by default.
+   * @type {boolean}
+   */
+  send?: boolean
   /**
    * @description Enable or disable the email feature. Enabled by default.
    * @type {boolean}
    */
   email?: boolean
   /**
    * @description Show or hide the regular wallet options when email is enabled. Enabled by default.
+   * @deprecated - This property will be removed in the next major release. Please use `features.collapseWallets` instead.
    * @type {boolean}
    */
   emailShowWallets?: boolean
   /**
    * @description Enable or disable the socials feature. Enabled by default.
-   * @type {FeaturesSocials[]}
+   * @type {SocialProvider[]}
    */
-  socials?: FeaturesSocials[] | false
+  socials?: SocialProvider[] | false
   /**
    * @description Enable or disable the history feature. Enabled by default.
    * @type {boolean}
@@ -1042,6 +1049,25 @@ export type Features = {
    * @default false
    */
   legalCheckbox?: boolean
+  /**
+   * @description The order of the connect methods. This is experimental and subject to change.
+   * @default ['email', 'social', 'wallet']
+   * @type {('email' | 'social' | 'wallet')[]}
+   */
+  connectMethodsOrder?: ConnectMethod[]
+  /**
+   * @
+   * @description The order of the wallet features. This is experimental and subject to change.
+   * @default ['receive' | 'onramp' | 'swaps' | 'send']
+   * @type {('receive' | 'onramp' | 'swaps' | 'send')[]}
+   */
+  walletFeaturesOrder?: WalletFeature[]
+  /**
+   * @description Enable or disable the collapse wallets as a single "Continue with wallet" button for simple UI in connect page.
+   * This can be activated when only have another connect method like email or social activated along with wallets.
+   * @default false
+   */
+  collapseWallets?: boolean
 }
 
 export type FeaturesKeys = keyof Features