Merge pull request #12 from OpenZeppelin/feature/plat-6727-evm-adapter-enhance-ui-customizations-using-rainbowkits

feat(adapter): add native prop-based ConnectButton customizations

Author: pasevin

packages/adapter-evm/src/index.ts

@@ -3,6 +3,9 @@ import EvmAdapter from './adapter';
 // Re-export the main adapter class
 export { EvmAdapter };
 
+// Export RainbowKit customization types
+export * from './wallet/rainbowkit/types';
+
 // Optionally re-export types if they need to be accessible directly
 // export * from './types';
 

packages/adapter-evm/src/wallet/README.md

@@ -109,13 +109,53 @@ const rainbowKitAppConfig = {
     // modalSize: 'compact',
     // appInfo: { appName: 'My dApp', learnMoreUrl: 'https://learnmore.example' }
   }, // as RainbowKitProviderProps (or a subset for type safety)
+
+  // Enhanced UI customizations using RainbowKit's native prop types
+  customizations: {
+    connectButton: {
+      // Uses RainbowKit's native ConnectButton props - no custom types needed!
+      // Refer to RainbowKit docs: https://www.rainbowkit.com/docs/connect-button
+
+      chainStatus: 'none', // Hide network switcher dropdown
+      accountStatus: 'full', // Show full account info when connected
+      label: 'Connect Wallet', // Custom connect button text
+      showBalance: true, // Show/hide balance display
+
+      // Responsive configurations are also supported:
+      // showBalance: {
+      //   smallScreen: false,
+      //   largeScreen: true,
+      // },
+      // accountStatus: {
+      //   smallScreen: 'avatar',
+      //   largeScreen: 'full',
+      // },
+    },
+  },
 };
 
 export default rainbowKitAppConfig;
 ```
 
 - **`wagmiParams`**: Contains parameters for RainbowKit's `getDefaultConfig()` (e.g., `appName`, `projectId`). The adapter will use these but will override `chains` and `transports` based on its own `networkConfig` and `AppConfigService` RPC overrides.
 - **`providerProps`**: Contains props to be spread onto the `<RainbowKitProvider />` component (e.g., `theme`, `modalSize`).
+- **`customizations`**: Enhanced UI customizations that leverage RainbowKit's native prop types directly. This section allows you to configure the ConnectButton component using RainbowKit's official props.
+
+#### RainbowKit ConnectButton Customizations
+
+The `customizations.connectButton` section supports all native RainbowKit ConnectButton props:
+
+- **`chainStatus`**: Controls network switcher visibility
+  - `'full'`: Show full chain name and icon (default)
+  - `'icon'`: Show only chain icon
+  - `'name'`: Show only chain name
+  - `'none'`: Hide network switcher completely
+- **`accountStatus`**: Controls account info display when connected
+  - `'full'`: Show full account info (default)
+  - `'avatar'`: Show only avatar
+  - `'address'`: Show only address
+- **`label`**: Custom text for the connect button when disconnected
+- **`showBalance`**: Show/hide balance in the button (boolean or responsive object)
 
 ### 3. `loadConfigModule` (Application-Provided Importer)
 

packages/adapter-evm/src/wallet/rainbowkit/components.tsx

@@ -8,6 +8,9 @@ import { cn, logger } from '@openzeppelin/transaction-form-utils';
 
 import { CustomConnectButton } from '../components';
 import { WagmiProviderInitializedContext } from '../context/wagmi-context';
+import { evmUiKitManager } from '../evmUiKitManager';
+
+import { extractRainbowKitCustomizations } from './types';
 
 const MIN_COMPONENT_LOADING_DISPLAY_MS = 1000; // 1 second artificial delay
 
@@ -23,9 +26,18 @@ export const RainbowKitConnectButton: React.FC<BaseComponentProps> = (props) =>
   const [isLoadingComponent, setIsLoadingComponent] = useState(true);
   const [showComponentLoadingOverride, setShowComponentLoadingOverride] = useState(false);
   const componentLoadingTimerRef = useRef<NodeJS.Timeout | null>(null);
+  const [managerState, setManagerState] = useState(evmUiKitManager.getState());
 
   const isWagmiProviderReady = useContext(WagmiProviderInitializedContext);
 
+  // Subscribe to UI kit manager state changes
+  useEffect(() => {
+    const unsubscribe = evmUiKitManager.subscribe(() => {
+      setManagerState(evmUiKitManager.getState());
+    });
+    return unsubscribe;
+  }, []);
+
   useEffect(() => {
     let isMounted = true;
     setIsLoadingComponent(true);
@@ -109,5 +121,22 @@ export const RainbowKitConnectButton: React.FC<BaseComponentProps> = (props) =>
     return <CustomConnectButton {...props} />;
   }
 
-  return <Component {...props} />;
+  // Extract custom configuration from the manager state
+  const kitConfig = managerState.currentFullUiKitConfig?.kitConfig;
+  const customizations = extractRainbowKitCustomizations(kitConfig);
+  const connectButtonConfig = customizations?.connectButton;
+
+  // Merge props: base props + custom configuration + any overrides from props
+  // This allows the config to set defaults while still allowing prop overrides
+  const finalProps = {
+    ...connectButtonConfig, // Apply custom configuration from config
+    ...props, // Allow props to override configuration
+  };
+
+  logger.debug('RainbowKitConnectButton', 'Rendering with configuration:', {
+    configFromFile: connectButtonConfig,
+    finalProps: finalProps,
+  });
+
+  return <Component {...finalProps} />;
 };

packages/adapter-evm/src/wallet/rainbowkit/index.ts

@@ -1,4 +1,5 @@
 export * from './components';
 export * from './utils';
 export * from './componentFactory';
+export * from './types';
 export { createRainbowKitWagmiConfig, getWagmiConfigForRainbowKit } from './config-service';

packages/adapter-evm/src/wallet/rainbowkit/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Custom RainbowKit configuration types for enhanced UI control
+ */
+/**
+ * Re-export RainbowKit's native types for ConnectButton props
+ * This ensures we use the exact same types that RainbowKit expects,
+ * reducing maintenance burden and letting RainbowKit handle type validation
+ */
+// Import RainbowKit's native ConnectButton types
+import type { ConnectButton } from '@rainbow-me/rainbowkit';
+
+/**
+ * Extract the props type from RainbowKit's ConnectButton component
+ * This gives us the exact same types that RainbowKit uses internally
+ */
+export type RainbowKitConnectButtonProps = React.ComponentProps<typeof ConnectButton>;
+
+/**
+ * Custom UI configuration that uses RainbowKit's native types
+ * This extends our configuration system while leveraging RainbowKit's own type definitions
+ */
+export interface RainbowKitCustomizations {
+  /**
+   * Configuration for the RainbowKit ConnectButton component
+   * Uses RainbowKit's native prop types for type safety and compatibility
+   */
+  connectButton?: Partial<RainbowKitConnectButtonProps>;
+}
+
+/**
+ * Type guard to check if an object contains RainbowKit customizations
+ */
+export function isRainbowKitCustomizations(obj: unknown): obj is RainbowKitCustomizations {
+  return typeof obj === 'object' && obj !== null && 'connectButton' in obj;
+}
+
+/**
+ * Utility to extract RainbowKit customizations from a kit config
+ */
+export function extractRainbowKitCustomizations(
+  kitConfig: Record<string, unknown> | undefined
+): RainbowKitCustomizations | undefined {
+  if (!kitConfig || !kitConfig.customizations) {
+    return undefined;
+  }
+
+  const customizations = kitConfig.customizations;
+  return isRainbowKitCustomizations(customizations) ? customizations : undefined;
+}

packages/core/public/app.config.local.json

@@ -6,7 +6,7 @@
         "kitConfig": {
           "showInjectedConnector": false,
           "components": {
-            "exclude": []
+            "exclude": ["NetworkSwitcher"]
           }
         }
       }

packages/core/src/config/wallet/rainbowkit.config.ts

@@ -1,6 +1,9 @@
 // packages/core/src/config/wallet/rainbowkit.config.ts
 import { type RainbowKitProvider, darkTheme } from '@rainbow-me/rainbowkit';
 
+// Import the custom configuration types from the EVM adapter
+import type { RainbowKitCustomizations } from '@openzeppelin/transaction-form-adapter-evm';
+
 // For WalletConnect project ID, appName, wallets, ssr options for getDefaultConfig
 // RainbowKit doesn't export a single neat type for all getDefaultConfig options other than `chains` and `transports`.
 // Users can refer to RainbowKit docs for available options for getDefaultConfig.
@@ -19,6 +22,7 @@ import { type RainbowKitProvider, darkTheme } from '@rainbow-me/rainbowkit';
  *                   The adapter will override `chains` and `transports`.
  *  - `providerProps`: An object with props for the `<RainbowKitProvider />` component
  *                     (e.g., `theme`, `locale`, `modalSize`, `initialChain`, `appInfo`).
+ *  - `customizations`: Additional UI customizations that use RainbowKit's native prop types
  */
 
 // Infer props type from RainbowKitProvider for stronger typing on the user's side for providerProps.
@@ -48,6 +52,30 @@ const rainbowKitAppConfig = {
       learnMoreUrl: 'https://openzeppelin.com',
     },
   } as Partial<InferredRainbowKitProviderProps>, // User can cast or ensure their object matches
+
+  /**
+   * Custom UI enhancements using RainbowKit's native prop types
+   * These options extend RainbowKit's functionality using their own type system
+   * Refer to RainbowKit docs for available props: https://www.rainbowkit.com/docs/connect-button
+   */
+  customizations: {
+    connectButton: {
+      // Use RainbowKit's native props directly - no custom types needed!
+      chainStatus: 'none', // Hide the network switcher dropdown
+      // accountStatus: 'full', // Default behavior - can be 'full', 'avatar', 'address'
+      // label: 'Connect Wallet', // Custom connect button text
+      // showBalance: true, // Show/hide balance - can be boolean or responsive object
+      // Example responsive configuration:
+      // showBalance: {
+      //   smallScreen: false,
+      //   largeScreen: true,
+      // },
+      // accountStatus: {
+      //   smallScreen: 'avatar',
+      //   largeScreen: 'full',
+      // },
+    },
+  } as RainbowKitCustomizations,
 };
 
 export default rainbowKitAppConfig;