feat: create wallet flow (#2974)

.changeset/rare-spoons-trade.md

@@ -0,0 +1,38 @@
+---
+'@reown/appkit-scaffold-ui': patch
+'@apps/laboratory': patch
+'@reown/appkit-core': patch
+'@apps/gallery': patch
+'@reown/appkit-ui': patch
+'@apps/demo': patch
+'@examples/html-ethers': patch
+'@examples/html-ethers5': patch
+'@examples/html-wagmi': patch
+'@examples/next-ethers': patch
+'@examples/next-wagmi': patch
+'@examples/react-ethers': patch
+'@examples/react-ethers5': patch
+'@examples/react-solana': patch
+'@examples/react-wagmi': patch
+'@examples/vue-ethers5': patch
+'@examples/vue-solana': patch
+'@examples/vue-wagmi': patch
+'@reown/appkit-adapter-ethers': patch
+'@reown/appkit-adapter-ethers5': patch
+'@reown/appkit-adapter-polkadot': patch
+'@reown/appkit-adapter-solana': patch
+'@reown/appkit-adapter-wagmi': patch
+'@reown/appkit': patch
+'@reown/appkit-utils': patch
+'@reown/appkit-cdn': patch
+'@reown/appkit-common': patch
+'@reown/appkit-ethers': patch
+'@reown/appkit-ethers5': patch
+'@reown/appkit-polyfills': patch
+'@reown/appkit-siwe': patch
+'@reown/appkit-solana': patch
+'@reown/appkit-wagmi': patch
+'@reown/appkit-wallet': patch
+---
+
+Added create wallet flow in connect modal

apps/gallery/stories/composites/wui-chip.stories.ts

@@ -29,6 +29,14 @@ export default {
       options: iconOptions,
       control: { type: 'select' }
     },
+    imageIcon: {
+      options: iconOptions,
+      control: { type: 'select' }
+    },
+    imageIconSize: {
+      options: ['xxs', 'xs', 'sm', 'md', 'lg'],
+      control: { type: 'select' }
+    },
     disabled: {
       control: { type: 'boolean' }
     }
@@ -43,5 +51,7 @@ export const Default: Component = {
       href=${args.href}
       ?disabled=${args.disabled}
       .imageSrc=${args.imageSrc}
+      .imageIcon=${args.imageIcon}
+      .imageIconSize=${args.imageIconSize}
     ></wui-chip>`
 }

apps/laboratory/tests/shared/pages/ModalPage.ts

@@ -325,6 +325,10 @@ export class ModalPage {
     return page
   }
 
+  async clickWalletGuideGetStarted() {
+    await this.page.getByTestId('w3m-wallet-guide-get-started').click()
+  }
+
   async promptSiwe() {
     const siweSign = this.page.getByTestId('w3m-connecting-siwe-sign')
     await expect(siweSign, 'Siwe prompt sign button should be visible').toBeVisible({

apps/laboratory/tests/shared/validators/ModalValidator.ts

@@ -200,6 +200,13 @@ export class ModalValidator {
     await expect(onrampButton).toBeVisible()
   }
 
+  async expectWalletGuide(_library: string, guide: 'get-started' | 'explore') {
+    const walletGuide = this.page.getByTestId(
+      guide === 'explore' ? 'w3m-wallet-guide-explore' : 'w3m-wallet-guide-get-started'
+    )
+    await expect(walletGuide).toBeVisible()
+  }
+
   async expectAccountNameFound(name: string) {
     const suggestion = this.page.getByTestId('account-name-suggestion').getByText(name)
     await expect(suggestion).toBeVisible()

apps/laboratory/tests/wallet.spec.ts

@@ -181,6 +181,14 @@ sampleWalletTest('it should disconnect and close modal when connecting from wall
   await walletPage.page.waitForTimeout(500)
 })
 
+sampleWalletTest('it should display wallet guide and show explore option', async ({ library }) => {
+  await modalPage.openConnectModal()
+  await modalValidator.expectWalletGuide(library, 'get-started')
+  await modalPage.clickWalletGuideGetStarted()
+  await modalValidator.expectWalletGuide(library, 'explore')
+  await modalPage.closeModal()
+})
+
 sampleWalletTest('it should disconnect as expected', async () => {
   await modalPage.qrCodeFlow(modalPage, walletPage)
   await modalValidator.expectConnected()

packages/core/src/controllers/RouterController.ts

@@ -39,6 +39,7 @@ export interface RouterControllerState {
     | 'WalletCompatibleNetworks'
     | 'ChooseAccountName'
     | 'Connect'
+    | 'Create'
     | 'ConnectingExternal'
     | 'ConnectingFarcaster'
     | 'ConnectingWalletConnect'

packages/core/src/utils/TypeUtil.ts

@@ -933,3 +933,5 @@ export type Features = {
 }
 
 export type FeaturesKeys = keyof Features
+
+export type WalletGuideType = 'get-started' | 'explore'

packages/scaffold-ui/exports/index.ts

@@ -115,3 +115,4 @@ export * from '../src/partials/w3m-connect-walletconnect-widget/index.js'
 export * from '../src/partials/w3m-connector-list/index.js'
 export * from '../src/partials/w3m-all-wallets-widget/index.js'
 export * from '../src/partials/w3m-account-auth-button/index.js'
+export * from '../src/partials/w3m-wallet-guide/index.js'

packages/scaffold-ui/src/modal/w3m-router/index.ts

@@ -75,6 +75,8 @@ export class W3mRouter extends LitElement {
         return html`<w3m-choose-account-name-view></w3m-choose-account-name-view>`
       case 'Connect':
         return html`<w3m-connect-view></w3m-connect-view>`
+      case 'Create':
+        return html`<w3m-connect-view walletGuide="explore"></w3m-connect-view>`
       case 'ConnectingWalletConnect':
         return html`<w3m-connecting-wc-view></w3m-connecting-wc-view>`
       case 'ConnectingExternal':

packages/scaffold-ui/src/partials/w3m-email-login-widget/index.ts

@@ -2,11 +2,12 @@ import {
   ChainController,
   ConnectorController,
   CoreHelperUtil,
-  OptionsController
+  OptionsController,
+  type WalletGuideType
 } from '@reown/appkit-core'
 import { customElement } from '@reown/appkit-ui'
 import { LitElement, html } from 'lit'
-import { state } from 'lit/decorators.js'
+import { property, state } from 'lit/decorators.js'
 import { ref, createRef } from 'lit/directives/ref.js'
 import type { Ref } from 'lit/directives/ref.js'
 import styles from './styles.js'
@@ -33,6 +34,8 @@ export class W3mEmailLoginWidget extends LitElement {
 
   @state() private error = ''
 
+  @property() private walletGuide: WalletGuideType = 'get-started'
+
   public constructor() {
     super()
     this.unsubscribe.push(
@@ -57,10 +60,7 @@ export class W3mEmailLoginWidget extends LitElement {
 
   // -- Render -------------------------------------------- //
   public override render() {
-    const socials = OptionsController.state.features?.socials
     const email = OptionsController.state.features?.email
-    const multipleConnectors = this.connectors.length > 1
-    const enableWallets = OptionsController.state.enableWallets
 
     if (!this.authConnector || !email) {
       return null
@@ -79,12 +79,7 @@ export class W3mEmailLoginWidget extends LitElement {
         ${this.submitButtonTemplate()}${this.loadingTemplate()}
         <input type="submit" hidden />
       </form>
-
-      ${socials || !multipleConnectors || !enableWallets
-        ? null
-        : html`<wui-flex .padding=${['xxs', '0', '0', '0'] as const}>
-            <wui-separator text="or"></wui-separator>
-          </wui-flex>`}
+      ${this.separatorTemplate()}
     `
   }
 
@@ -105,6 +100,27 @@ export class W3mEmailLoginWidget extends LitElement {
       : null
   }
 
+  private separatorTemplate() {
+    const socials = OptionsController.state.features?.socials
+    const multipleConnectors = this.connectors.length > 1
+    const enableWallets = OptionsController.state.enableWallets
+
+    const hideSeparator = socials || !multipleConnectors || !enableWallets
+
+    if (hideSeparator && this.walletGuide === 'get-started') {
+      return null
+    }
+
+    if (socials && socials.length > 0) {
+      return null
+    }
+
+    return html`
+      <wui-flex .padding=${['xxs', '0', '0', '0'] as const}>
+        <wui-separator text="or"></wui-separator>
+      </wui-flex>
+    `
+  }
   private loadingTemplate() {
     return this.loading
       ? html`<wui-loading-spinner size="md" color="accent-100"></wui-loading-spinner>`

packages/scaffold-ui/src/partials/w3m-header/index.ts

@@ -31,6 +31,7 @@ function headings() {
 
   return {
     Connect: `Connect ${isEmail ? 'Email' : ''} Wallet`,
+    Create: 'Create Wallet',
     ChooseAccountName: undefined,
     Account: undefined,
     AccountSettings: undefined,

packages/scaffold-ui/src/partials/w3m-social-login-widget/index.ts

@@ -7,11 +7,12 @@ import {
   OptionsController,
   RouterController,
   SnackController,
-  type SocialProvider
+  type SocialProvider,
+  type WalletGuideType
 } from '@reown/appkit-core'
 import { customElement } from '@reown/appkit-ui'
 import { LitElement, html } from 'lit'
-import { state } from 'lit/decorators.js'
+import { state, property } from 'lit/decorators.js'
 
 import styles from './styles.js'
 import { ifDefined } from 'lit/directives/if-defined.js'
@@ -36,6 +37,8 @@ export class W3mSocialLoginWidget extends LitElement {
 
   @state() private authConnector = this.connectors.find(c => c.type === 'AUTH')
 
+  @property() public walletGuide: WalletGuideType = 'get-started'
+
   public constructor() {
     super()
     this.unsubscribe.push(
@@ -152,7 +155,7 @@ export class W3mSocialLoginWidget extends LitElement {
     const walletConnectConnector = this.connectors.find(c => c.id === 'walletConnect')
     const enableWallets = OptionsController.state.enableWallets
 
-    if (walletConnectConnector && enableWallets) {
+    if ((walletConnectConnector && enableWallets) || this.walletGuide === 'explore') {
       return html`<wui-separator text="or"></wui-separator>`
     }
 

packages/scaffold-ui/src/partials/w3m-wallet-guide/index.ts

@@ -0,0 +1,69 @@
+import { customElement } from '@reown/appkit-ui'
+import { LitElement, html } from 'lit'
+import styles from './styles.js'
+import { RouterController, type WalletGuideType } from '@reown/appkit-core'
+import { property } from 'lit/decorators.js'
+
+@customElement('w3m-wallet-guide')
+export class W3mWalletGuide extends LitElement {
+  public static override styles = styles
+
+  // -- State & Properties -------------------------------- //
+  @property() public walletGuide: WalletGuideType = 'get-started'
+
+  // -- Render -------------------------------------------- //
+  public override render() {
+    return this.walletGuide === 'explore'
+      ? html`<wui-flex
+          class="wallet-guide"
+          flexDirection="column"
+          alignItems="center"
+          justifyContent="center"
+          rowGap="xs"
+          data-testid="w3m-wallet-guide-explore"
+        >
+          <wui-text variant="small-400" color="fg-200" align="center">
+            Looking for a self-custody wallet?
+          </wui-text>
+
+          <wui-flex class="chip-box">
+            <wui-chip
+              imageIcon="walletConnectLightBrown"
+              icon="externalLink"
+              variant="transparent"
+              href="https://explorer.walletconnect.com"
+              title="Visit our Explorer"
+            ></wui-chip>
+          </wui-flex>
+        </wui-flex>`
+      : html`<wui-flex
+          columnGap="4xs"
+          flexDirection="row"
+          alignItems="center"
+          justifyContent="center"
+        >
+          <wui-text variant="small-400" class="title" color="fg-200"
+            >Haven't got a wallet?</wui-text
+          >
+          <wui-link
+            data-testid="w3m-wallet-guide-get-started"
+            color="blue-100"
+            class="get-started-link"
+            @click=${this.onGetStarted}
+          >
+            Get started
+          </wui-link>
+        </wui-flex>`
+  }
+
+  // -- Private ------------------------------------------- //
+  private onGetStarted() {
+    RouterController.push('Create')
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'w3m-wallet-guide': W3mWalletGuide
+  }
+}

packages/scaffold-ui/src/partials/w3m-wallet-guide/styles.ts

@@ -0,0 +1,17 @@
+import { css } from 'lit'
+
+export default css`
+  wui-flex {
+    width: 100%;
+  }
+
+  .wallet-guide {
+    width: 100%;
+  }
+
+  .chip-box {
+    width: fit-content;
+    background-color: var(--wui-color-gray-glass-005);
+    border-radius: var(--wui-border-radius-3xl);
+  }
+`