From 17182fdb84699babb52d5be89ffedee4bf91427f Mon Sep 17 00:00:00 2001
From: Leonardo Zizzamia <leonardo.zizzamia@gmail.com>
Date: Wed, 18 Sep 2024 16:34:52 +0800
Subject: [PATCH] docs: wallet story time (#1276)

---
 site/docs/components/WalletComponents.tsx   |   2 +-
 site/docs/pages/transaction/transaction.mdx |   2 +-
 site/docs/pages/wallet/wallet.mdx           | 222 +++++++++++++-------
 3 files changed, 144 insertions(+), 82 deletions(-)

diff --git a/site/docs/components/WalletComponents.tsx b/site/docs/components/WalletComponents.tsx
index 30eb9d07ae..0a9fbed540 100644
--- a/site/docs/components/WalletComponents.tsx
+++ b/site/docs/components/WalletComponents.tsx
@@ -9,7 +9,7 @@ type WalletComponentsReact = {
 export default function WalletComponents({ children }: WalletComponentsReact) {
   return (
     <App>
-      <div className="mt-10 mb-28 flex justify-center">{children}</div>
+      <div className="my-10 flex justify-center">{children}</div>
     </App>
   );
 }
diff --git a/site/docs/pages/transaction/transaction.mdx b/site/docs/pages/transaction/transaction.mdx
index 8f1e933f96..e5ca314414 100644
--- a/site/docs/pages/transaction/transaction.mdx
+++ b/site/docs/pages/transaction/transaction.mdx
@@ -297,7 +297,7 @@ The components are designed to work together hierarchically. For each component,
 - `<TransactionToastLabel />` - Displays the label text in the transaction toast notification.
 - `<TransactionToastAction />` - Provides additional actions within the transaction toast notification.
 
-## Props
+## Component types
 
 - [`TransactionButtonReact`](/transaction/types#transactionbuttonreact)
 - [`TransactionError`](/transaction/types#transactionerror)
diff --git a/site/docs/pages/wallet/wallet.mdx b/site/docs/pages/wallet/wallet.mdx
index 7c9cec1071..416920775e 100644
--- a/site/docs/pages/wallet/wallet.mdx
+++ b/site/docs/pages/wallet/wallet.mdx
@@ -1,12 +1,15 @@
 ---
 title: <Wallet /> · OnchainKit
-description: Wallet components & utilities
+description: The `<Wallet />` components provides an interface for users to connect their Smart Wallet with their identity information like Basename and ETH balance.
 ---
 
 import { 
   ConnectWallet,
+  ConnectWalletText,
   Wallet,
   WalletDropdown,
+  WalletDropdownBasename,
+  WalletDropdownFundLink,
   WalletDropdownLink,
   WalletDropdownDisconnect,
 } from '@coinbase/onchainkit/wallet';
@@ -23,16 +26,64 @@ import WalletComponents from '../../components/WalletComponents';
 
 # `<Wallet />`
 
-The Wallet components provide a comprehensive interface for users to connect their Smart Wallet, view their identity information, and manage their wallet connection. Before using them, ensure you've completed all Getting Started steps.
+The `<Wallet />` components provides an interface for users to connect their 
+Smart Wallet with their identity information like Basename and ETH balance.
 
-## Usage
+It features built-in polished user experiences for both web and mobile web, 
+making it incredibly easy to enhance with drop-in components.
+
+Before using them, ensure you've completed all [Getting Started steps](/getting-started).
+
+## Walkthrough
+
+::::steps
+
+### Set up your wallet connections
+
+Kick off your wallet connection setup by configuring the `wagmi` provider.
+
+And make sure to update the `appName` as that will be displayed to 
+the user when they connect their wallet.
+
+```tsx twoslash
+import { ReactNode } from 'react';
+import { WagmiProvider, createConfig, http } from 'wagmi';
+import { baseSepolia } from 'wagmi/chains';
+import { coinbaseWallet } from 'wagmi/connectors';
+
+const wagmiConfig = createConfig({
+  chains: [baseSepolia],
+  connectors: [
+    coinbaseWallet({
+      appName: 'onchainkit',
+    }),
+  ],
+  ssr: true,
+  transports: {
+    [baseSepolia.id]: http(),
+  },
+});
+
+function App({ children }: { children: ReactNode }) {
+  return <WagmiProvider config={wagmiConfig}>{children}</WagmiProvider>;
+}
+```
+
+### Drop in the `<Wallet />` components
+
+Experience the magic by simply dropping in the `<Wallet />` component 
+and watch it seamlessly come to life.
+<br />
+Additionally, you can see the [`<Identity>`](/identity/identity) components 
+like [`<Avatar>`](/identity/avatar), [`<Name>`](/identity/name), 
+and [`<Address>`](/identity/address) are used in a composable way. 
+Explore their documentation pages to discover various customization options.
 
 ```tsx twoslash
 import { // [!code focus]
   ConnectWallet, // [!code focus]
   Wallet, // [!code focus]
   WalletDropdown, // [!code focus]
-  WalletDropdownLink, // [!code focus]
   WalletDropdownDisconnect, // [!code focus]
 } from '@coinbase/onchainkit/wallet'; // [!code focus]
 import {
@@ -40,7 +91,6 @@ import {
   Avatar,
   Name,
   Identity,
-  EthBalance,
 } from '@coinbase/onchainkit/identity';
 import { color } from '@coinbase/onchainkit/theme';
 
@@ -57,11 +107,7 @@ export function WalletComponents() {
             <Avatar />
             <Name />
             <Address className={color.foregroundMuted} />
-            <EthBalance />
           </Identity>
-          <WalletDropdownLink icon="wallet" href="https://keys.coinbase.com"> // [!code focus]
-            Wallet // [!code focus]
-          </WalletDropdownLink> // [!code focus]
           <WalletDropdownDisconnect /> // [!code focus]
         </WalletDropdown> // [!code focus]
       </Wallet> // [!code focus]
@@ -81,26 +127,30 @@ export function WalletComponents() {
         <Avatar />
         <Name />
         <Address className={color.foregroundMuted} />
-        <EthBalance />
       </Identity>
-      <WalletDropdownLink icon="wallet" href="https://keys.coinbase.com">
-        Wallet
-      </WalletDropdownLink>
       <WalletDropdownDisconnect />
     </WalletDropdown>
   </Wallet>
 </WalletComponents>
 
-### Override styles
+### Drop in pre-made wallet components
 
-You can override component styles using `className`.
+Expand the user experience with pre-made components like [`<WalletDropdownLink>`](/wallet/wallet-dropdown-link),
+[`<WalletDropdownBasename>`](/wallet/wallet-dropdown-basename),
+ [`<WalletDropdownFundLink>`](/wallet/wallet-dropdown-fund-link), 
+ or `<EthBalance>`, to help you build a seamless wallet experience for your users.
+<br />
+The `<WalletDropdownLink>` is highly versatile and will likely be your go-to choice 
+for adding more links to the dropdown, connecting your users to various pages of your onchain app.
 
 ```tsx twoslash
 import {
   ConnectWallet,
   Wallet,
   WalletDropdown,
-  WalletDropdownLink,
+  WalletDropdownBasename, // [!code focus]
+  WalletDropdownFundLink, // [!code focus]
+  WalletDropdownLink, // [!code focus]
   WalletDropdownDisconnect,
 } from '@coinbase/onchainkit/wallet';
 import {
@@ -108,139 +158,147 @@ import {
   Avatar,
   Name,
   Identity,
-  EthBalance,
+  EthBalance, // [!code focus]
 } from '@coinbase/onchainkit/identity';
-import { color } from '@coinbase/onchainkit/theme';
-// ---cut-before---
+
 // omitted for brevity
 
 <Wallet>
-  <ConnectWallet className='bg-blue-800'>
+  <ConnectWallet>
     <Avatar className="h-6 w-6" />
-    <Name className='text-white' />
+    <Name />
   </ConnectWallet>
   <WalletDropdown>
     <Identity 
-      className="px-4 pt-3 pb-2 hover:bg-blue-200" 
+      className="px-4 pt-3 pb-2" 
       hasCopyAddressOnClick
     >
       <Avatar />
       <Name />
       <Address />
-      <EthBalance />
+      <EthBalance /> // [!code focus]
     </Identity>
-    <WalletDropdownLink 
-      className='hover:bg-blue-200' 
-      icon="wallet" 
-      href="https://keys.coinbase.com"
-    >
-      Wallet
-    </WalletDropdownLink>
-    <WalletDropdownDisconnect className='hover:bg-blue-200' />
+    <WalletDropdownBasename /> // [!code focus]
+    <WalletDropdownLink // [!code focus]
+      icon="wallet" // [!code focus]
+      href="https://keys.coinbase.com" // [!code focus]
+    > // [!code focus]
+      Wallet // [!code focus]
+    </WalletDropdownLink> // [!code focus]
+    <WalletDropdownFundLink /> // [!code focus]
+    <WalletDropdownDisconnect />
   </WalletDropdown>
 </Wallet>
 ```
 
 <WalletComponents>
   <Wallet>
-    <ConnectWallet className='bg-blue-800'>
+    <ConnectWallet>
       <Avatar className="h-6 w-6" />
-      <Name className='text-white' />
+      <Name />
     </ConnectWallet>
     <WalletDropdown>
-      <Identity className="px-4 pt-3 pb-2 hover:bg-blue-200" hasCopyAddressOnClick>
+      <Identity className="px-4 pt-3 pb-2" hasCopyAddressOnClick>
         <Avatar />
         <Name />
         <Address className={color.foregroundMuted} />
         <EthBalance />
       </Identity>
+      <WalletDropdownBasename />
       <WalletDropdownLink 
-        className='hover:bg-blue-200' 
         icon="wallet" 
         href="https://keys.coinbase.com"
       >
         Wallet
       </WalletDropdownLink>
-      <WalletDropdownDisconnect className='hover:bg-blue-200' />
+      <WalletDropdownFundLink />
+      <WalletDropdownDisconnect />
     </WalletDropdown>
   </Wallet>
 </WalletComponents>
 
-### Override text
+### Customize Connect button text and style
+
+Each OnchainKit component offers the flexibility to customize `className` 
+and adjust the style of the React components it represents.
 
-You can override component text using `text`.
+Customize the connect wallet text by using directly the `<ConnectWalletText>` component.
 
 ```tsx twoslash
 import {
   ConnectWallet,
+  ConnectWalletText,
   Wallet,
+  WalletDropdown,
+  WalletDropdownLink,
+  WalletDropdownDisconnect,
 } from '@coinbase/onchainkit/wallet';
 import {
+  Address,
   Avatar,
   Name,
+  Identity,
+  EthBalance,
 } from '@coinbase/onchainkit/identity';
+import { color } from '@coinbase/onchainkit/theme';
 // ---cut-before---
 // omitted for brevity
 
 <Wallet>
-  <ConnectWallet text="Log In"> // [!code focus]
-    <Avatar/>
-    <Name/>
+  <ConnectWallet className='bg-blue-800'> // [!code focus]
+    <ConnectWalletText>Log In</ConnectWalletText> // [!code focus]
+    <Avatar className="h-6 w-6" /> // [!code focus]
+    <Name className='text-white' /> // [!code focus]
   </ConnectWallet>
+  <WalletDropdown>
+    <Identity 
+      className="px-4 pt-3 pb-2 hover:bg-blue-200" // [!code focus]
+      hasCopyAddressOnClick
+    >
+      <Avatar />
+      <Name />
+      <Address />
+      <EthBalance />
+    </Identity>
+    <WalletDropdownLink 
+      className='hover:bg-blue-200' // [!code focus]
+      icon="wallet" 
+      href="https://keys.coinbase.com"
+    >
+      Wallet
+    </WalletDropdownLink>
+    <WalletDropdownDisconnect className='hover:bg-blue-200' /> // [!code focus]
+  </WalletDropdown>
 </Wallet>
 ```
 
 <WalletComponents>
   <Wallet>
-    <ConnectWallet text="Log In">
+    <ConnectWallet className='bg-blue-800'>
+      <ConnectWalletText>Log In</ConnectWalletText>
       <Avatar className="h-6 w-6" />
-      <Name />
+      <Name className='text-white' />
     </ConnectWallet>
     <WalletDropdown>
-      <Identity className="px-4 pt-3 pb-2" hasCopyAddressOnClick>
+      <Identity className="px-4 pt-3 pb-2 hover:bg-blue-200" hasCopyAddressOnClick>
         <Avatar />
         <Name />
         <Address className={color.foregroundMuted} />
         <EthBalance />
       </Identity>
-      <WalletDropdownLink icon="wallet" href="https://keys.coinbase.com">
+      <WalletDropdownLink 
+        className='hover:bg-blue-200' 
+        icon="wallet" 
+        href="https://keys.coinbase.com"
+      >
         Wallet
       </WalletDropdownLink>
-      <WalletDropdownDisconnect />
+      <WalletDropdownDisconnect className='hover:bg-blue-200' />
     </WalletDropdown>
   </Wallet>
 </WalletComponents>
 
-## Required providers
-
-If you are using any of the provided components, you will need to install
-and configure `wagmi` and wrap your app in `<WagmiProvider>`.
-
-```tsx twoslash
-import { ReactNode } from 'react';
-import { WagmiProvider, createConfig, http } from 'wagmi';
-import { baseSepolia } from 'wagmi/chains';
-import { coinbaseWallet } from 'wagmi/connectors';
-
-const wagmiConfig = createConfig({
-  chains: [baseSepolia],
-  connectors: [
-    coinbaseWallet({
-      appName: 'onchainkit',
-    }),
-  ],
-  ssr: true,
-  transports: {
-    [baseSepolia.id]: http(),
-  },
-});
-
-function App({ children }: { children: ReactNode }) {
-  return <WagmiProvider config={wagmiConfig}>{children}</WagmiProvider>;
-}
-```
-
-## Use wallet aggregator
+### Use RainbowKit for wallet aggregation
 
 You can expand the wallet connection options by using the `withWalletAggregator` prop in the `<ConnectWallet />` component. This will present users with a list of recommended and other wallets to choose from.
 
@@ -271,7 +329,7 @@ import {
 // omitted for brevity
 
 <Wallet>
-  <ConnectWallet withWalletAggregator>
+  <ConnectWallet withWalletAggregator>  // [!code focus]
     <Avatar className="h-6 w-6" />
     <Name />
   </ConnectWallet>
@@ -364,7 +422,7 @@ export default OnchainProviders;
 :::
 
 <AppWithRK>
-  <div className="mt-10 mb-28 flex justify-center">
+  <div className="my-10 flex justify-center">
     <Wallet>
       <ConnectWallet withWalletAggregator>
         <Avatar className="h-6 w-6" />
@@ -389,6 +447,8 @@ export default OnchainProviders;
   </div>
 </AppWithRK>
 
+::::
+
 ## Components
 
 The components are designed to work together hierarchically. For each component, ensure the following:
@@ -409,9 +469,11 @@ Additional components for customizing the wallet interface include:
 - `<Address />` - Shows the user's wallet address.
 - `<EthBalance />` - Displays the user's ETH balance.
 
-The Wallet component automatically handles the wallet connection state and updates the UI accordingly. You need to wrap your application or relevant part of it with these components to provide a complete wallet interaction experience.
+The Wallet component automatically handles the wallet connection state and updates the UI accordingly. 
+You need to wrap your application or relevant part of it with these components 
+to provide a complete wallet interaction experience.
 
-## Props
+## Component types
 
 - [`WalletReact`](/wallet/types#walletreact)
 - [`ConnectWalletReact`](/wallet/types#connectwalletreact)