@lumiapassport/ui-kit 1.12.5 → 1.13.0

package/README.md

@@ -13,9 +13,9 @@ React UI components and hooks for Lumia Passport - a secure, user-friendly authe
 ## Installation
 
 ```bash
-npm install @lumiapassport/ui-kit 
+npm install @lumiapassport/ui-kit
 # or
-pnpm add @lumiapassport/ui-kit 
+pnpm add @lumiapassport/ui-kit
 # or
 yarn add @lumiapassport/ui-kit
 ```
@@ -24,31 +24,28 @@ yarn add @lumiapassport/ui-kit
 
 ### 1. Setup QueryClient (Required)
 
-The UI Kit requires `@tanstack/react-query` for state management. First, create a query client:
+The UI Kit requires `@tanstack/react-query` for query management. First, create a query client:
 
 ```tsx
 // queryClient.ts
-import { QueryClient } from '@tanstack/react-query';
+import { QueryClient } from '@tanstack/react-query'
 
 export const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 1000 * 60 * 5, // 5 minutes
-      gcTime: 1000 * 60 * 10, // 10 minutes
-      refetchOnWindowFocus: false,
-      retry: false,
-    },
-  },
-});
+  defaultOptions: {}
+})
 ```
 
 ### 2. Wrap your app with providers
 
 ```tsx
-import { QueryClientProvider } from '@tanstack/react-query';
-import { LumiaPassportProvider } from '@lumiapassport/ui-kit';
-import '@lumiapassport/ui-kit/dist/styles.css';
-import { queryClient } from './queryClient';
+import {
+  //
+  LumiaPassportProvider,
+  LumiaPassportSessionProvider,
+  LumiaRainbowKitProvider
+} from '@lumiapassport/ui-kit'
+
+import { queryClient } from './queryClient'
 
 function Root() {
   return (
@@ -56,25 +53,51 @@ function Root() {
       <LumiaPassportProvider
         projectId="your-project-id" // Get from Lumia Passport Dashboard
       >
-        <YourApp />
+        <LumiaRainbowKitProvider>
+          <LumiaPassportSessionProvider>
+            <YourApp />
+          </LumiaPassportSessionProvider>
+        </LumiaRainbowKitProvider>
       </LumiaPassportProvider>
     </QueryClientProvider>
-  );
+  )
 }
 ```
 
 ### 3. Add the Connect Button
 
 ```tsx
-import { ConnectWalletButton } from '@lumiapassport/ui-kit';
+import { ConnectWalletButton } from '@lumiapassport/ui-kit'
 
 function YourApp() {
   return (
     <div>
       <h1>My App</h1>
-      <ConnectWalletButton label="Sign in" mode="compact"/>
+      <ConnectWalletButton label="Sign in" />
     </div>
-  );
+  )
+}
+```
+
+### 3.1 (Optional)
+
+Custom unconnected button can be provided via ConnectButton prop.
+Prop consumes standart HTMLButton component and will provide required onClick to it
+
+```tsx
+import { ConnectWalletButton } from '@lumiapassport/ui-kit'
+
+function CustomButtonComponent(props: HTMLAttributes<HTMLButtonElement>) => {
+  return (<button {...props}/>)
+}
+
+function YourApp() {
+  return (
+    <div>
+      <h1>My App</h1>
+      <ConnectWalletButton label="Sign in" ConnectButton={CustomButtonComponent} />
+    </div>
+  )
 }
 ```
 
@@ -109,20 +132,23 @@ That's it! The `ConnectWalletButton` provides a complete authentication UI with
   projectId="your-project-id"
   initialConfig={{
     // UI customization
+    preferedColorMode?: 'light', // 'light'  | 'dark'
+
     ui: {
-      theme: 'dark', // 'light' | 'dark' | 'auto'
       title: 'Welcome to MyApp',
       subtitle: 'Sign in to continue',
+
+      // beta
+      dialogClassName: 'string',
+
       authOrder: ['email', 'passkey', 'social'],
-      modal: {
-        width: '420px',
-        borderRadius: '24px'
-      },
+
       branding: {
         tagline: 'Powered by MPC',
         link: { text: 'Learn More', url: 'https://example.com/docs' },
       },
-      // Custom colors
+
+      // TO BE DEPRECATED, cssv is used
       colors: {
         dark: {
           background: '#060117',
@@ -241,20 +267,21 @@ That's it! The `ConnectWalletButton` provides a complete authentication UI with
 
 ## Using Hooks
 
-> **Note:** The old `useLumiaSession` and `LumiaSessionProvider` names are deprecated but still supported for backward compatibility. They will show a console warning and will be removed in v2.0.0. Please migrate to the new names: `useLumiaPassportSession` and `LumiaPassportSessionProvider`.
+> **Note:** The `useLumiaPassportSession` hook is based on pure Zustand store so if you already using hook consider 2 options: 1) refactor state extarction so it uses zustand state extraction feature. 2) consider using new session hooks: `useLumiaPassportAccountSession`, `useLumiaPassportAddress` etc. Otherwise you might experience excessive re-rendering issues
 
-### useLumiaPassportSession - Authentication and Session State
+### useLumiaPassportAccountSession, useLumiaPassportLoadingStatus, useLumiaPassportBalance, useLumiaPassportIFrameReady, useLumiaPassportAddress, useLumiaPassportError, useLumiaPassportLoadingStatus, useLumiaPassportRecoveryUserId, useLumiaPassportHasServerVault
 
 ```tsx
-import { useLumiaPassportSession } from '@lumiapassport/ui-kit';
+import { useLumiaPassportAccountSession, useLumiaPassportLoadingStatus } from '@lumiapassport/ui-kit'
 
 function MyComponent() {
-  const { session, isLoading } = useLumiaPassportSession();
+  const session = useLumiaPassportAccountSession() // const session = useLumiaPassportSession(s => s.session) - with prev hook &  Zustand state extraction feature
+  const { isSessionLoading } = useLumiaPassportLoadingStatus()
 
-  if (isLoading) return <div>Loading...</div>;
+  if (isSessionLoading) return <div>Loading...</div>
 
   if (!session) {
-    return <div>Not authenticated. Please connect your wallet.</div>;
+    return <div>Not authenticated. Please connect your wallet.</div>
   }
 
   return (
@@ -264,30 +291,30 @@ function MyComponent() {
       <p>Wallet Address: {session.ownerAddress}</p>
       <p>Smart Account: {session.accountAddress}</p>
     </div>
-  );
+  )
 }
 ```
 
 ### useSendTransaction - Send Transactions
 
 ```tsx
-import { useSendTransaction } from '@lumiapassport/ui-kit';
+import { useSendTransaction } from '@lumiapassport/ui-kit'
 
 function TransactionExample() {
-  const { sendTransaction, isPending } = useSendTransaction();
+  const { sendTransaction, isPending } = useSendTransaction()
 
   const handleSend = async () => {
     try {
       const userOpHash = await sendTransaction({
         to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
         value: '1000000000000000000', // 1 ETH in wei
-        data: '0x', // Optional contract call data
-      });
-      console.log('UserOp hash:', userOpHash);
+        data: '0x' // Optional contract call data
+      })
+      console.log('UserOp hash:', userOpHash)
     } catch (error) {
-      console.error('Transaction failed:', error);
+      console.error('Transaction failed:', error)
     }
-  };
+  }
 
   return (
     <div>
@@ -295,7 +322,7 @@ function TransactionExample() {
         {isPending ? 'Sending...' : 'Send Transaction'}
       </button>
     </div>
-  );
+  )
 }
 ```
 
@@ -304,39 +331,40 @@ function TransactionExample() {
 For direct control without using the React hook, you can use `sendUserOperation` function:
 
 ```tsx
-import { sendUserOperation, useLumiaPassportSession } from '@lumiapassport/ui-kit';
+import { sendUserOperation, useLumiaPassportAccountSession } from '@lumiapassport/ui-kit'
 
 function DirectTransactionExample() {
-  const { session } = useLumiaPassportSession();
+  const session = useLumiaPassportAccountSession()
 
   const handleSend = async () => {
     if (!session) {
-      console.error('No active session');
-      return;
+      console.error('No active session')
+      return
     }
 
     try {
       // Send transaction directly with full control
       const userOpHash = await sendUserOperation(
-        session,                                    // Required: session from useLumiaPassportSession
+        session, // Required: session from useLumiaPassportAccountSession
         '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', // to address
-        '1000000000000000000',                      // value in wei (1 ETH)
-        '0x',                                       // data (optional contract call)
-        'standard',                                 // fee type: 'economy' | 'standard' | 'fast'
-        'v0.7'                                      // EntryPoint version
-      );
+        '1000000000000000000', // value in wei (1 ETH)
+        '0x', // data (optional contract call)
+        'standard', // fee type: 'economy' | 'standard' | 'fast'
+        'v0.7' // EntryPoint version
+      )
 
-      console.log('Transaction submitted:', userOpHash);
+      console.log('Transaction submitted:', userOpHash)
     } catch (error) {
-      console.error('Transaction failed:', error);
+      console.error('Transaction failed:', error)
     }
-  };
+  }
 
-  return <button onClick={handleSend}>Send Transaction</button>;
+  return <button onClick={handleSend}>Send Transaction</button>
 }
 ```
 
 **When to use:**
+
 - ✅ Use `useSendTransaction()` hook for React components (automatic session management)
 - ✅ Use `sendUserOperation()` function for custom logic, utility functions, or non-React code
 
@@ -347,43 +375,46 @@ Deploy the smart account contract immediately after registration. This is **opti
 **Smart behavior:** Automatically checks if account is already deployed and skips transaction to save gas.
 
 ```tsx
-import { deployAccount, useLumiaPassportSession } from '@lumiapassport/ui-kit';
+import { deployAccount, useLumiaPassportAccountSession } from '@lumiapassport/ui-kit'
 
 function DeployAccountExample() {
-  const { session } = useLumiaPassportSession();
+  const session = useLumiaPassportAccountSession()
 
   const handleDeploy = async () => {
-    if (!session) return;
+    if (!session) return
 
     try {
       // Deploy account with minimal gas cost (skips if already deployed)
-      const userOpHash = await deployAccount(session, 'economy');
+      const userOpHash = await deployAccount(session, 'economy')
 
       if (userOpHash) {
-        console.log('Account deployed:', userOpHash);
+        console.log('Account deployed:', userOpHash)
       } else {
-        console.log('Account already deployed, skipped');
+        console.log('Account already deployed, skipped')
       }
     } catch (error) {
-      console.error('Deployment failed:', error);
+      console.error('Deployment failed:', error)
     }
-  };
+  }
 
-  return <button onClick={handleDeploy}>Deploy Account</button>;
+  return <button onClick={handleDeploy}>Deploy Account</button>
 }
 ```
 
 **Return values:**
+
 - Returns `userOpHash` (string) - if deployment was needed and executed
 - Returns `null` - if account already deployed (saves gas)
 
 **Advanced usage:**
+
 ```tsx
 // Force deployment even if already deployed (not recommended)
-const hash = await deployAccount(session, 'economy', { force: true });
+const hash = await deployAccount(session, 'economy', { force: true })
 ```
 
 **Why use this?**
+
 - ✅ **Pre-deploy** account before first real transaction
 - ✅ **No user consent** required (safe minimal operation)
 - ✅ **Cleaner UX** - separate deployment from first payment
@@ -391,6 +422,7 @@ const hash = await deployAccount(session, 'economy', { force: true });
 - ⚠️ **Optional** - accounts auto-deploy on first transaction anyway
 
 **How it works:**
+
 1. Checks if smart account contract exists on-chain
 2. If exists: returns `null` immediately (no gas cost)
 3. If not exists: sends minimal UserOperation (`to=0x0, value=0, data=0x`)
@@ -401,69 +433,77 @@ const hash = await deployAccount(session, 'economy', { force: true });
 Sign structured data according to [EIP-712](https://eips.ethereum.org/EIPS/eip-712) standard. This is commonly used for off-chain signatures in dApps (e.g., NFT marketplace orders, gasless transactions, permit signatures).
 
 ```tsx
-import { signTypedData, useLumiaPassportSession } from '@lumiapassport/ui-kit';
+import { signTypedData, useLumiaPassportAccountSession } from '@lumiapassport/ui-kit'
 
 function SignatureExample() {
-  const { session } = useLumiaPassportSession();
+  const session = useLumiaPassportAccountSession()
 
   const handleSign = async () => {
-    if (!session) return;
+    if (!session) return
 
     try {
       // Define EIP712 typed data
       const signature = await signTypedData(session, {
         domain: {
-          name: 'MyDApp',              // Your dApp name (must match contract)
-          version: '1',                // Contract version
-          chainId: 994,                // Lumia Prism Testnet
-          verifyingContract: '0x...',  // Your contract address (REQUIRED in production!)
+          name: 'MyDApp', // Your dApp name (must match contract)
+          version: '1', // Contract version
+          chainId: 994, // Lumia Prism Testnet
+          verifyingContract: '0x...' // Your contract address (REQUIRED in production!)
         },
         types: {
           Order: [
             { name: 'tokenIds', type: 'uint256[]' },
             { name: 'price', type: 'uint256' },
-            { name: 'deadline', type: 'uint256' },
-          ],
+            { name: 'deadline', type: 'uint256' }
+          ]
         },
         primaryType: 'Order',
         message: {
           tokenIds: [1n, 2n, 3n],
           price: 1000000000000000000n, // 1 token in wei
-          deadline: BigInt(Math.floor(Date.now() / 1000) + 3600), // 1 hour from now
-        },
-      });
+          deadline: BigInt(Math.floor(Date.now() / 1000) + 3600) // 1 hour from now
+        }
+      })
 
-      console.log('Signature:', signature);
+      console.log('Signature:', signature)
 
       // Verify signature (optional)
-      const { recoverTypedDataAddress } = await import('viem');
+      const { recoverTypedDataAddress } = await import('viem')
       const recoveredAddress = await recoverTypedDataAddress({
-        domain: { /* same domain */ },
-        types: { /* same types */ },
+        domain: {
+          /* same domain */
+        },
+        types: {
+          /* same types */
+        },
         primaryType: 'Order',
-        message: { /* same message */ },
-        signature,
-      });
+        message: {
+          /* same message */
+        },
+        signature
+      })
 
-      console.log('Signer:', recoveredAddress); // Should match session.ownerAddress
+      console.log('Signer:', recoveredAddress) // Should match session.ownerAddress
     } catch (error) {
-      console.error('Signing failed:', error);
+      console.error('Signing failed:', error)
     }
-  };
+  }
 
-  return <button onClick={handleSign}>Sign Message</button>;
+  return <button onClick={handleSign}>Sign Message</button>
 }
 ```
 
 **Important Notes about ERC-4337 Smart Accounts:**
 
 In Account Abstraction (ERC-4337), there are **two addresses**:
+
 1. **Owner Address (EOA)** - The address that signs messages/transactions
 2. **Smart Account Address** - The contract wallet address
 
 ⚠️ **Critical:** The signature is created by the **owner address** (EOA), NOT the smart account address!
 
 **Compatibility with existing protocols:**
+
 - ✅ **Works:** Protocols that verify signatures off-chain (e.g., your backend verifies the owner EOA signature)
 - ⚠️ **May not work:** Protocols designed for EOA wallets that store and verify against `msg.sender` or wallet address
   - Example: Uniswap Permit2, some NFT marketplaces
@@ -472,16 +512,19 @@ In Account Abstraction (ERC-4337), there are **two addresses**:
   - **Solution:** Use ERC-1271 signature validation in your smart contracts (allows contracts to validate signatures)
 
 **Domain Configuration:**
+
 - In production, use your actual `verifyingContract` address (not zero address!)
 - The `domain` parameters must match exactly between frontend and smart contract
 - The `chainId` should match the network you're deploying to
 
 **Technical Details:**
+
 - Shows a MetaMask-like confirmation modal with structured message preview
 - All BigInt values are supported in the message
 - Signature can be verified using `viem.recoverTypedDataAddress()` - will return owner EOA address
 
 **When to use signTypedData:**
+
 - ✅ Custom backend signature verification (you control the verification logic)
 - ✅ Gasless transactions with meta-transaction relayers
 - ✅ DAO voting and governance (off-chain signatures)
@@ -491,13 +534,13 @@ In Account Abstraction (ERC-4337), there are **two addresses**:
 ### prepareUserOperation - Prepare for Backend Submission
 
 ```tsx
-import { prepareUserOperation, useLumiaPassportSession } from '@lumiapassport/ui-kit';
+import { prepareUserOperation, useLumiaPassportAccountSession } from '@lumiapassport/ui-kit'
 
 function BackendSubmissionExample() {
-  const { session } = useLumiaPassportSession();
+  const session = useLumiaPassportAccountSession()
 
   const handlePrepare = async () => {
-    if (!session) return;
+    if (!session) return
 
     // Prepare and sign UserOp without sending to bundler
     const { userOp, userOpHash } = await prepareUserOperation(
@@ -507,7 +550,7 @@ function BackendSubmissionExample() {
       '0x', // data
       'standard', // fee type: 'economy' | 'standard' | 'fast'
       'v0.7' // EntryPoint version
-    );
+    )
 
     // Send to backend for validation and submission
     await fetch('/api/submit-transaction', {
@@ -517,76 +560,116 @@ function BackendSubmissionExample() {
         userOp,
         userOpHash,
         ownerAddress: session.ownerAddress // for signature verification
-      }),
-    });
-  };
+      })
+    })
+  }
 
-  return (
-    <button onClick={handlePrepare}>
-      Prepare & Send to Backend
-    </button>
-  );
+  return <button onClick={handlePrepare}>Prepare & Send to Backend</button>
 }
 ```
 
 **Backend example (using @lumiapassport/core):**
 
 ```typescript
-import { sendUserOperationRaw, getUserOperationReceipt } from '@lumiapassport/core';
-import { recoverAddress } from 'viem';
+import { getUserOperationReceipt, sendUserOperationRaw } from '@lumiapassport/core'
+import { recoverAddress } from 'viem'
 
 // Receive from frontend
-const { userOp, userOpHash, ownerAddress } = await request.json();
+const { userOp, userOpHash, ownerAddress } = await request.json()
 
 // Verify signature
 const recoveredAddress = await recoverAddress({
   hash: userOpHash,
-  signature: userOp.signature,
-});
+  signature: userOp.signature
+})
 
 if (recoveredAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
-  throw new Error('Invalid signature');
+  throw new Error('Invalid signature')
 }
 
 // Submit to bundler - returns userOpHash
-const submittedUserOpHash = await sendUserOperationRaw(userOp);
+const submittedUserOpHash = await sendUserOperationRaw(userOp)
 
 // Poll for receipt to get transaction hash and status
 const waitForReceipt = async (userOpHash: string, maxAttempts = 60, delayMs = 1000) => {
   for (let i = 0; i < maxAttempts; i++) {
-    const receipt = await getUserOperationReceipt(userOpHash as `0x${string}`);
+    const receipt = await getUserOperationReceipt(userOpHash as `0x${string}`)
     if (receipt) {
       return {
         success: receipt.success,
         transactionHash: receipt.receipt?.transactionHash,
-        blockNumber: receipt.receipt?.blockNumber,
-      };
+        blockNumber: receipt.receipt?.blockNumber
+      }
     }
-    await new Promise(resolve => setTimeout(resolve, delayMs));
+    await new Promise((resolve) => setTimeout(resolve, delayMs))
   }
-  throw new Error('Transaction timeout');
-};
+  throw new Error('Transaction timeout')
+}
 
-const result = await waitForReceipt(submittedUserOpHash);
+const result = await waitForReceipt(submittedUserOpHash)
 return {
   success: result.success,
   transactionHash: result.transactionHash,
   blockNumber: result.blockNumber
-};
+}
 ```
 
-## Components
+### useLumiaPassportOpen - Programmatic LumiaPassport Dialog Control
+
+Control the Lumia Passport dialog programmatically.
+
+```tsx
+import { PageKey, useLumiaPassportOpen } from '@lumiapassport/ui-kit'
+
+function CustomAuthButton() {
+  const { isOpen, open: openLumiaPassport, close } = useLumiaPassportOpen()
+
+  return (
+    <div>
+      <button onClick={() => openLumiaPassport(PageKey.AUTH)}>Sign In</button>
+      <button onClick={() => openLumiaPassport(PageKey.RECEIVE)}>Receive LUMIA</button>
+
+      <button onClick={close}>Close Dialog</button>
+    </div>
+  )
+}
+```
+
+### useLumiaPassportColorMode - Theme Control
+
+Control light/dark mode for Lumia Passport UI. Use hook to sync colorMode inside your App instead of any local colorMode states
+
+```tsx
+import { useLumiaPassportColorMode } from '@lumiapassport/ui-kit'
+
+function ThemeSelector() {
+  const { colorMode, setColorMode } = useLumiaPassportColorMode()
+
+  return (
+    <div>
+      <p>Current theme: {colorMode}</p>
+      <button onClick={() => setColorMode('light')}>Light</button>
+      <button onClick={() => setColorMode('dark')}>Dark</button>
+    </div>
+  )
+}
+```
 
-### ConnectWalletButton
+### ThemeToggle - Quick Theme Switcher
 
-Pre-built button with authentication modal.
+Pre-built theme toggle button component to use in combo with useLumiaPassportColorMode.
 
 ```tsx
-<ConnectWalletButton
-  className="custom-class"
-  onConnect={(user) => console.log('Connected:', user)}
-  onDisconnect={() => console.log('Disconnected')}
-/>
+import { ThemeToggle } from '@lumiapassport/ui-kit'
+
+function AppHeader() {
+  return (
+    <header>
+      <h1>My App</h1>
+      <ThemeToggle />
+    </header>
+  )
+}
 ```
 
 ## Authentication Methods
@@ -635,46 +718,14 @@ Connect existing wallets (MetaMask, WalletConnect, etc.).
 
 ## Styling
 
-### Using Built-in Themes
-
-```tsx
-import '@lumiapassport/ui-kit/dist/styles.css';
-
-<LumiaPassportProvider
-  projectId="your-project-id"
-  initialConfig={{
-    ui: {
-      theme: 'dark', // or 'light', 'auto'
-    }
-  }}
->
-```
-
-### Custom Styling
-
-Override CSS variables for custom branding:
-
-```css
-.lumia-scope {
-  --lumia-primary: #6366f1;
-  --lumia-background: #0f172a;
-  --lumia-surface: #1e293b;
-  --lumia-text-primary: #f8fafc;
-  --lumia-text-secondary: #cbd5e1;
-}
-```
+...to be updated
 
 ## TypeScript Support
 
 Full TypeScript support with exported types:
 
 ```tsx
-import type {
-  LumiaPassportConfig,
-  User,
-  AuthProvider,
-  WalletInfo,
-} from '@lumiapassport/ui-kit';
+import type { AuthProvider, LumiaPassportConfig, User, WalletInfo } from '@lumiapassport/ui-kit'
 ```
 
 ## Examples