@openzeppelin/ui-react 1.0.0

package/dist/index.cjs

@@ -0,0 +1,909 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let react = require("react");
+react = __toESM(react);
+let _openzeppelin_ui_utils = require("@openzeppelin/ui-utils");
+let react_jsx_runtime = require("react/jsx-runtime");
+let _openzeppelin_ui_components = require("@openzeppelin/ui-components");
+
+//#region src/hooks/AdapterContext.tsx
+/**
+* AdapterContext.tsx
+*
+* This file defines the React Context used for the adapter singleton pattern.
+* It provides types and the context definition, but the actual implementation
+* is in the AdapterProvider component.
+*
+* The adapter singleton pattern ensures that only one adapter instance exists
+* per network configuration, which is critical for consistent wallet connection
+* state across the application.
+*/
+/**
+* The React Context that provides adapter registry access throughout the app
+* Components can access this through the useAdapterContext hook
+*/
+const AdapterContext = (0, react.createContext)(null);
+
+//#endregion
+//#region src/hooks/AdapterProvider.tsx
+/**
+* AdapterProvider.tsx
+*
+* This file implements the Adapter Provider component which manages a registry of
+* adapter instances. It's a key part of the adapter singleton pattern which ensures
+* that only one adapter instance exists per network configuration.
+*
+* The adapter registry is shared across the application via React Context, allowing
+* components to access the same adapter instances and maintain consistent wallet
+* connection state.
+*
+* IMPORTANT: This implementation needs special care to avoid React state update errors
+* during component rendering. Direct state updates during render are not allowed, which
+* is why adapter loading is controlled carefully.
+*/
+/**
+* Provider component that manages adapter instances centrally
+* to avoid creating multiple instances of the same adapter.
+*
+* This component:
+* 1. Maintains a registry of adapter instances by network ID
+* 2. Tracks loading states for adapters being initialized
+* 3. Provides a function to get or load adapters for specific networks
+* 4. Ensures adapter instances are reused when possible
+*/
+function AdapterProvider({ children, resolveAdapter }) {
+	const [adapterRegistry, setAdapterRegistry] = (0, react.useState)({});
+	const [loadingNetworks, setLoadingNetworks] = (0, react.useState)(/* @__PURE__ */ new Set());
+	(0, react.useEffect)(() => {
+		const adapterCount = Object.keys(adapterRegistry).length;
+		if (adapterCount > 0) _openzeppelin_ui_utils.logger.info("AdapterProvider", `Registry contains ${adapterCount} adapters:`, {
+			networkIds: Object.keys(adapterRegistry),
+			loadingCount: loadingNetworks.size,
+			loadingNetworkIds: Array.from(loadingNetworks)
+		});
+	}, [adapterRegistry, loadingNetworks]);
+	/**
+	* Function to get or create an adapter for a network
+	*
+	* IMPORTANT: The actual adapter loading is handled in the useConfiguredAdapterSingleton hook
+	* to avoid React state updates during render, which would cause errors.
+	*
+	* This function:
+	* 1. Returns existing adapters immediately if available
+	* 2. Reports loading state for adapters being initialized
+	* 3. Initiates adapter loading when needed
+	*/
+	const getAdapterForNetwork = (0, react.useCallback)((networkConfig) => {
+		if (!networkConfig) return {
+			adapter: null,
+			isLoading: false
+		};
+		const networkId = networkConfig.id;
+		_openzeppelin_ui_utils.logger.debug("AdapterProvider", `Adapter requested for network ${networkId}`);
+		if (adapterRegistry[networkId]) {
+			_openzeppelin_ui_utils.logger.debug("AdapterProvider", `Using existing adapter for network ${networkId}`);
+			return {
+				adapter: adapterRegistry[networkId],
+				isLoading: false
+			};
+		}
+		if (loadingNetworks.has(networkId)) {
+			_openzeppelin_ui_utils.logger.debug("AdapterProvider", `Adapter for network ${networkId} is currently loading`);
+			return {
+				adapter: null,
+				isLoading: true
+			};
+		}
+		setLoadingNetworks((prev) => {
+			const newSet = new Set(prev);
+			newSet.add(networkId);
+			return newSet;
+		});
+		_openzeppelin_ui_utils.logger.info("AdapterProvider", `Starting adapter initialization for network ${networkId} (${networkConfig.name})`);
+		resolveAdapter(networkConfig).then((adapter) => {
+			_openzeppelin_ui_utils.logger.info("AdapterProvider", `Adapter for network ${networkId} loaded successfully`, {
+				type: adapter.constructor.name,
+				objectId: Object.prototype.toString.call(adapter)
+			});
+			setAdapterRegistry((prev) => ({
+				...prev,
+				[networkId]: adapter
+			}));
+			setLoadingNetworks((prev) => {
+				const newSet = new Set(prev);
+				newSet.delete(networkId);
+				return newSet;
+			});
+		}).catch((error) => {
+			_openzeppelin_ui_utils.logger.error("AdapterProvider", `Error loading adapter for network ${networkId}:`, error);
+			setLoadingNetworks((prev) => {
+				const newSet = new Set(prev);
+				newSet.delete(networkId);
+				return newSet;
+			});
+		});
+		return {
+			adapter: null,
+			isLoading: true
+		};
+	}, [
+		adapterRegistry,
+		loadingNetworks,
+		resolveAdapter
+	]);
+	const contextValue = (0, react.useMemo)(() => ({ getAdapterForNetwork }), [getAdapterForNetwork]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AdapterContext.Provider, {
+		value: contextValue,
+		children
+	});
+}
+
+//#endregion
+//#region src/hooks/WalletStateContext.tsx
+const WalletStateContext = (0, react.createContext)(void 0);
+/**
+* Hook to access wallet state from WalletStateProvider.
+* @throws Error if used outside of WalletStateProvider
+*/
+function useWalletState() {
+	const context = react.default.useContext(WalletStateContext);
+	if (context === void 0) throw new Error("useWalletState must be used within a WalletStateProvider");
+	return context;
+}
+
+//#endregion
+//#region src/hooks/useAdapterContext.ts
+/**
+* useAdapterContext.ts
+*
+* This file provides a hook to access the AdapterContext throughout the application.
+* It's a critical part of the adapter singleton pattern, allowing components to
+* access the centralized adapter registry.
+*
+* The adapter singleton pattern ensures:
+* - Only one adapter instance exists per network
+* - Wallet connection state is consistent across the app
+* - Better performance by eliminating redundant adapter initialization
+*/
+/**
+* Hook to access the adapter context
+*
+* This hook provides access to the getAdapterForNetwork function which
+* retrieves or creates adapter instances from the singleton registry.
+*
+* Components should typically use useConfiguredAdapterSingleton instead
+* of this hook directly, as it handles React state update timing properly.
+*
+* @throws Error if used outside of an AdapterProvider context
+* @returns The adapter context value
+*/
+function useAdapterContext() {
+	const context = (0, react.useContext)(AdapterContext);
+	if (!context) throw new Error("useAdapterContext must be used within an AdapterProvider");
+	return context;
+}
+
+//#endregion
+//#region src/hooks/WalletStateProvider.tsx
+/**
+* Configures the adapter's UI kit and returns the UI provider component and hooks.
+*/
+async function configureAdapterUiKit(adapter, loadConfigModule, programmaticOverrides = {}) {
+	try {
+		if (typeof adapter.configureUiKit === "function") {
+			_openzeppelin_ui_utils.logger.info("[WSP configureAdapterUiKit] Calling configureUiKit for adapter:", adapter?.networkConfig?.id);
+			await adapter.configureUiKit(programmaticOverrides, { loadUiKitNativeConfig: loadConfigModule });
+			_openzeppelin_ui_utils.logger.info("[WSP configureAdapterUiKit] configureUiKit completed for adapter:", adapter?.networkConfig?.id);
+		}
+		const providerComponent = adapter.getEcosystemReactUiContextProvider?.() || null;
+		const hooks = adapter.getEcosystemReactHooks?.() || null;
+		_openzeppelin_ui_utils.logger.info("[WSP configureAdapterUiKit]", "UI provider and hooks retrieved successfully.");
+		return {
+			providerComponent,
+			hooks
+		};
+	} catch (error) {
+		_openzeppelin_ui_utils.logger.error("[WSP configureAdapterUiKit]", "Error during adapter UI setup:", error);
+		throw error;
+	}
+}
+/**
+* @name WalletStateProvider
+* @description This provider is a central piece of the application's state management for wallet and network interactions.
+* It is responsible for:
+* 1. Managing the globally selected active network ID (`activeNetworkId`).
+* 2. Deriving the full `NetworkConfig` object (`activeNetworkConfig`) for the active network.
+* 3. Fetching and providing the corresponding `ContractAdapter` instance (`activeAdapter`) for the active network,
+*    leveraging the `AdapterProvider` to ensure adapter singletons.
+* 4. Storing and providing the `EcosystemSpecificReactHooks` (`walletFacadeHooks`) from the active adapter.
+* 5. Rendering the adapter-specific UI context provider (e.g., WagmiProvider for EVM) around its children,
+*    which is essential for the facade hooks to function correctly.
+* 6. Providing a function (`setActiveNetworkId`) to change the globally active network.
+*
+* Consumers use the `useWalletState()` hook to access this global state.
+* It should be placed high in the component tree, inside an `<AdapterProvider>`.
+*/
+function WalletStateProvider({ children, initialNetworkId = null, getNetworkConfigById, loadConfigModule }) {
+	const [currentGlobalNetworkId, setCurrentGlobalNetworkIdState] = (0, react.useState)(initialNetworkId);
+	const [currentGlobalNetworkConfig, setCurrentGlobalNetworkConfig] = (0, react.useState)(null);
+	const [globalActiveAdapter, setGlobalActiveAdapter] = (0, react.useState)(null);
+	const [isGlobalAdapterLoading, setIsGlobalAdapterLoading] = (0, react.useState)(false);
+	const [walletFacadeHooks, setWalletFacadeHooks] = (0, react.useState)(null);
+	const [AdapterUiContextProviderToRender, setAdapterUiContextProviderToRender] = (0, react.useState)(null);
+	const [uiKitConfigVersion, setUiKitConfigVersion] = (0, react.useState)(0);
+	const [programmaticUiKitConfig, setProgrammaticUiKitConfig] = (0, react.useState)(void 0);
+	const { getAdapterForNetwork } = useAdapterContext();
+	(0, react.useEffect)(() => {
+		const abortController = new AbortController();
+		async function fetchNetworkConfig() {
+			if (!currentGlobalNetworkId) {
+				if (!abortController.signal.aborted) setCurrentGlobalNetworkConfig(null);
+				return;
+			}
+			try {
+				const config = await Promise.resolve(getNetworkConfigById(currentGlobalNetworkId));
+				if (!abortController.signal.aborted) setCurrentGlobalNetworkConfig(config || null);
+			} catch (error) {
+				if (!abortController.signal.aborted) {
+					_openzeppelin_ui_utils.logger.error("[WSP fetchNetworkConfig]", "Failed to fetch network config:", error);
+					setCurrentGlobalNetworkConfig(null);
+				}
+			}
+		}
+		fetchNetworkConfig();
+		return () => abortController.abort();
+	}, [currentGlobalNetworkId, getNetworkConfigById]);
+	(0, react.useEffect)(() => {
+		const abortController = new AbortController();
+		async function loadAdapterAndConfigureUi() {
+			if (!currentGlobalNetworkConfig) {
+				if (!abortController.signal.aborted) {
+					setGlobalActiveAdapter(null);
+					setIsGlobalAdapterLoading(false);
+					setAdapterUiContextProviderToRender(null);
+					setWalletFacadeHooks(null);
+				}
+				return;
+			}
+			const { adapter: newAdapter, isLoading: newIsLoading } = getAdapterForNetwork(currentGlobalNetworkConfig);
+			if (abortController.signal.aborted) return;
+			setIsGlobalAdapterLoading(newIsLoading);
+			if (newAdapter && !newIsLoading) try {
+				const { providerComponent, hooks } = await configureAdapterUiKit(newAdapter, loadConfigModule, programmaticUiKitConfig);
+				if (!abortController.signal.aborted) {
+					setAdapterUiContextProviderToRender(() => providerComponent);
+					setWalletFacadeHooks(hooks);
+					setGlobalActiveAdapter(newAdapter);
+				}
+			} catch (error) {
+				if (!abortController.signal.aborted) {
+					_openzeppelin_ui_utils.logger.error("[WSP loadAdapterAndConfigureUi]", "Error during adapter UI setup:", error);
+					setAdapterUiContextProviderToRender(null);
+					setWalletFacadeHooks(null);
+				}
+			}
+			else if (!newAdapter && !newIsLoading) {
+				if (!abortController.signal.aborted) {
+					setAdapterUiContextProviderToRender(null);
+					setWalletFacadeHooks(null);
+					setGlobalActiveAdapter(null);
+				}
+			}
+		}
+		loadAdapterAndConfigureUi();
+		return () => abortController.abort();
+	}, [
+		currentGlobalNetworkConfig,
+		getAdapterForNetwork,
+		loadConfigModule,
+		uiKitConfigVersion,
+		programmaticUiKitConfig
+	]);
+	/**
+	* Callback to set the globally active network ID.
+	* Also clears dependent states (config, adapter, hooks) if the network ID is cleared.
+	*/
+	const setActiveNetworkIdCallback = (0, react.useCallback)((networkId) => {
+		_openzeppelin_ui_utils.logger.info("WalletStateProvider", `Setting global network ID to: ${networkId}`);
+		setCurrentGlobalNetworkIdState(networkId);
+		if (!networkId) {
+			setCurrentGlobalNetworkConfig(null);
+			setGlobalActiveAdapter(null);
+			setIsGlobalAdapterLoading(false);
+			setWalletFacadeHooks(null);
+		}
+	}, []);
+	/**
+	* Callback to explicitly trigger a re-configuration of the active adapter's UI kit.
+	* This is useful when a UI kit setting changes (e.g., via a wizard) without a network change.
+	*/
+	const reconfigureActiveAdapterUiKit = (0, react.useCallback)((uiKitConfig) => {
+		_openzeppelin_ui_utils.logger.info("WalletStateProvider", "Explicitly triggering UI kit re-configuration by bumping version.", uiKitConfig);
+		setProgrammaticUiKitConfig(uiKitConfig);
+		setUiKitConfigVersion((v) => v + 1);
+	}, [setProgrammaticUiKitConfig, setUiKitConfigVersion]);
+	const contextValue = (0, react.useMemo)(() => ({
+		activeNetworkId: currentGlobalNetworkId,
+		setActiveNetworkId: setActiveNetworkIdCallback,
+		activeNetworkConfig: currentGlobalNetworkConfig,
+		activeAdapter: globalActiveAdapter,
+		isAdapterLoading: isGlobalAdapterLoading,
+		walletFacadeHooks,
+		reconfigureActiveAdapterUiKit
+	}), [
+		currentGlobalNetworkId,
+		setActiveNetworkIdCallback,
+		currentGlobalNetworkConfig,
+		globalActiveAdapter,
+		isGlobalAdapterLoading,
+		walletFacadeHooks,
+		reconfigureActiveAdapterUiKit
+	]);
+	const ActualProviderToRender = AdapterUiContextProviderToRender;
+	let childrenToRender;
+	if (ActualProviderToRender) {
+		const key = `${globalActiveAdapter?.networkConfig?.ecosystem || "unknown"}-${globalActiveAdapter?.networkConfig?.id || "unknown"}`;
+		_openzeppelin_ui_utils.logger.info("[WSP RENDER]", "Rendering adapter-provided UI context provider:", ActualProviderToRender.displayName || ActualProviderToRender.name || "UnknownComponent", "with key:", key);
+		childrenToRender = /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ActualProviderToRender, { children }, key);
+	} else {
+		_openzeppelin_ui_utils.logger.info("[WSP RENDER]", "No adapter UI context provider to render. Rendering direct children.");
+		childrenToRender = children;
+	}
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(WalletStateContext.Provider, {
+		value: contextValue,
+		children: childrenToRender
+	});
+}
+
+//#endregion
+//#region src/hooks/AnalyticsContext.tsx
+/**
+* Analytics context for providing analytics functionality to React components.
+* Must be used within an AnalyticsProvider.
+*/
+const AnalyticsContext = (0, react.createContext)(null);
+/**
+* Internal hook to access analytics context.
+* Throws an error if used outside of an AnalyticsProvider.
+*
+* @internal
+* @throws Error if used outside of AnalyticsProvider
+*/
+const useAnalyticsContext = () => {
+	const context = (0, react.useContext)(AnalyticsContext);
+	if (!context) throw new Error("useAnalyticsContext must be used within an AnalyticsProvider");
+	return context;
+};
+
+//#endregion
+//#region src/hooks/AnalyticsProvider.tsx
+/**
+* Analytics Provider component.
+* Provides analytics functionality throughout the React component tree.
+*
+* @example
+* ```tsx
+* function App() {
+*   return (
+*     <AnalyticsProvider tagId={import.meta.env.VITE_GA_TAG_ID} autoInit={true}>
+*       <YourApp />
+*     </AnalyticsProvider>
+*   );
+* }
+* ```
+*/
+const AnalyticsProvider = ({ tagId, autoInit = true, children }) => {
+	(0, react.useEffect)(() => {
+		if (autoInit && tagId) _openzeppelin_ui_utils.AnalyticsService.initialize(tagId);
+	}, [tagId, autoInit]);
+	const contextValue = (0, react.useMemo)(() => ({
+		tagId,
+		isEnabled: () => _openzeppelin_ui_utils.AnalyticsService.isEnabled(),
+		initialize: (tagIdOverride) => {
+			const effectiveTagId = tagIdOverride || tagId;
+			if (effectiveTagId) _openzeppelin_ui_utils.AnalyticsService.initialize(effectiveTagId);
+		},
+		trackEvent: (eventName, parameters) => {
+			try {
+				_openzeppelin_ui_utils.AnalyticsService.trackEvent(eventName, parameters);
+			} catch (error) {
+				_openzeppelin_ui_utils.logger.error("AnalyticsProvider", "Error tracking event:", error);
+			}
+		},
+		trackPageView: (pageName, pagePath) => {
+			try {
+				_openzeppelin_ui_utils.AnalyticsService.trackPageView(pageName, pagePath);
+			} catch (error) {
+				_openzeppelin_ui_utils.logger.error("AnalyticsProvider", "Error tracking page view:", error);
+			}
+		},
+		trackNetworkSelection: (networkId, ecosystem) => {
+			try {
+				_openzeppelin_ui_utils.AnalyticsService.trackNetworkSelection(networkId, ecosystem);
+			} catch (error) {
+				_openzeppelin_ui_utils.logger.error("AnalyticsProvider", "Error tracking network selection:", error);
+			}
+		}
+	}), [tagId]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AnalyticsContext.Provider, {
+		value: contextValue,
+		children
+	});
+};
+
+//#endregion
+//#region src/hooks/useAnalytics.ts
+/**
+* Custom hook for accessing analytics functionality.
+*
+* This hook provides a convenient interface for tracking user interactions
+* throughout the application. It must be used within an AnalyticsProvider.
+*
+* For app-specific tracking methods, create a wrapper hook that uses this
+* hook and adds your custom tracking functions.
+*
+* @example
+* ```tsx
+* // Basic usage
+* function MyComponent() {
+*   const { trackEvent, trackPageView, isEnabled } = useAnalytics();
+*
+*   const handleClick = () => {
+*     trackEvent('button_clicked', { button_name: 'submit' });
+*   };
+*
+*   return (
+*     <div>
+*       Analytics enabled: {isEnabled().toString()}
+*       <button onClick={handleClick}>Submit</button>
+*     </div>
+*   );
+* }
+* ```
+*
+* @example
+* ```tsx
+* // Creating app-specific wrapper hook
+* function useMyAppAnalytics() {
+*   const analytics = useAnalytics();
+*
+*   return {
+*     ...analytics,
+*     trackFormSubmit: (formName: string) => {
+*       analytics.trackEvent('form_submitted', { form_name: formName });
+*     },
+*   };
+* }
+* ```
+*
+* @returns Analytics context with tracking methods and state
+* @throws Error if used outside of AnalyticsProvider
+*/
+const useAnalytics = () => {
+	try {
+		return useAnalyticsContext();
+	} catch {
+		throw new Error("useAnalytics must be used within an AnalyticsProvider");
+	}
+};
+
+//#endregion
+//#region src/hooks/useDerivedAccountStatus.ts
+const defaultAccountStatus = {
+	isConnected: false,
+	address: void 0,
+	chainId: void 0
+};
+/**
+* A custom hook that consumes useWalletState to get the walletFacadeHooks,
+* then calls the useAccount facade hook (if available) and returns a structured,
+* safely-accessed account status (isConnected, address, chainId).
+* Provides default values if the hook or its properties are unavailable.
+*/
+function useDerivedAccountStatus() {
+	const { walletFacadeHooks } = useWalletState();
+	const accountHookOutput = walletFacadeHooks?.useAccount ? walletFacadeHooks.useAccount() : void 0;
+	if ((0, _openzeppelin_ui_utils.isRecordWithProperties)(accountHookOutput)) return {
+		isConnected: "isConnected" in accountHookOutput && typeof accountHookOutput.isConnected === "boolean" ? accountHookOutput.isConnected : defaultAccountStatus.isConnected,
+		address: "address" in accountHookOutput && typeof accountHookOutput.address === "string" ? accountHookOutput.address : defaultAccountStatus.address,
+		chainId: "chainId" in accountHookOutput && typeof accountHookOutput.chainId === "number" ? accountHookOutput.chainId : defaultAccountStatus.chainId
+	};
+	return defaultAccountStatus;
+}
+
+//#endregion
+//#region src/hooks/useDerivedSwitchChainStatus.ts
+const defaultSwitchChainStatus = {
+	switchChain: void 0,
+	isSwitching: false,
+	error: null
+};
+/**
+* A custom hook that consumes `useWalletState` to get `walletFacadeHooks`,
+* then calls the `useSwitchChain` facade hook (if available) and returns a structured,
+* safely-accessed status and control function for network switching.
+* Provides default values if the hook or its properties are unavailable.
+*/
+function useDerivedSwitchChainStatus() {
+	const { walletFacadeHooks } = useWalletState();
+	const switchChainHookOutput = walletFacadeHooks?.useSwitchChain ? walletFacadeHooks.useSwitchChain() : void 0;
+	if ((0, _openzeppelin_ui_utils.isRecordWithProperties)(switchChainHookOutput)) return {
+		switchChain: "switchChain" in switchChainHookOutput && typeof switchChainHookOutput.switchChain === "function" ? switchChainHookOutput.switchChain : defaultSwitchChainStatus.switchChain,
+		isSwitching: "isPending" in switchChainHookOutput && typeof switchChainHookOutput.isPending === "boolean" ? switchChainHookOutput.isPending : defaultSwitchChainStatus.isSwitching,
+		error: "error" in switchChainHookOutput && switchChainHookOutput.error instanceof Error ? switchChainHookOutput.error : defaultSwitchChainStatus.error
+	};
+	return defaultSwitchChainStatus;
+}
+
+//#endregion
+//#region src/hooks/useDerivedChainInfo.ts
+const defaultChainInfo = {
+	currentChainId: void 0,
+	availableChains: []
+};
+/**
+* A custom hook that consumes `useWalletState` to get `walletFacadeHooks`,
+* then calls the `useChainId` and `useChains` facade hooks (if available)
+* and returns a structured object with this information.
+* Provides default values if the hooks or their properties are unavailable.
+*/
+function useDerivedChainInfo() {
+	const { walletFacadeHooks } = useWalletState();
+	let chainIdToReturn = defaultChainInfo.currentChainId;
+	const chainIdHookOutput = walletFacadeHooks?.useChainId ? walletFacadeHooks.useChainId() : void 0;
+	if (typeof chainIdHookOutput === "number") chainIdToReturn = chainIdHookOutput;
+	else if (chainIdHookOutput !== void 0) _openzeppelin_ui_utils.logger.warn("useDerivedChainInfo", "useChainId facade hook returned non-numeric value:", chainIdHookOutput);
+	let chainsToReturn = defaultChainInfo.availableChains;
+	const chainsHookOutput = walletFacadeHooks?.useChains ? walletFacadeHooks.useChains() : void 0;
+	if (Array.isArray(chainsHookOutput)) chainsToReturn = chainsHookOutput;
+	else if (chainsHookOutput !== void 0) _openzeppelin_ui_utils.logger.warn("useDerivedChainInfo", "useChains facade hook returned non-array value:", chainsHookOutput);
+	return {
+		currentChainId: chainIdToReturn,
+		availableChains: chainsToReturn
+	};
+}
+
+//#endregion
+//#region src/hooks/useDerivedConnectStatus.ts
+const defaultConnectStatus = {
+	connect: void 0,
+	connectors: [],
+	isConnecting: false,
+	error: null,
+	pendingConnector: void 0
+};
+/**
+* A custom hook that consumes `useWalletState` to get `walletFacadeHooks`,
+* then calls the `useConnect` facade hook (if available) and returns a structured,
+* safely-accessed status and control functions for wallet connection.
+*/
+function useDerivedConnectStatus() {
+	const { walletFacadeHooks } = useWalletState();
+	const connectHookOutput = walletFacadeHooks?.useConnect ? walletFacadeHooks.useConnect() : void 0;
+	if ((0, _openzeppelin_ui_utils.isRecordWithProperties)(connectHookOutput)) return {
+		connect: "connect" in connectHookOutput && typeof connectHookOutput.connect === "function" ? connectHookOutput.connect : defaultConnectStatus.connect,
+		connectors: "connectors" in connectHookOutput && Array.isArray(connectHookOutput.connectors) ? connectHookOutput.connectors : defaultConnectStatus.connectors,
+		isConnecting: "isPending" in connectHookOutput && typeof connectHookOutput.isPending === "boolean" ? connectHookOutput.isPending : "isLoading" in connectHookOutput && typeof connectHookOutput.isLoading === "boolean" ? connectHookOutput.isLoading : defaultConnectStatus.isConnecting,
+		error: "error" in connectHookOutput && connectHookOutput.error instanceof Error ? connectHookOutput.error : defaultConnectStatus.error,
+		pendingConnector: "pendingConnector" in connectHookOutput && typeof connectHookOutput.pendingConnector === "object" ? connectHookOutput.pendingConnector : defaultConnectStatus.pendingConnector
+	};
+	return defaultConnectStatus;
+}
+
+//#endregion
+//#region src/hooks/useDerivedDisconnect.ts
+const defaultDisconnectStatus = {
+	disconnect: void 0,
+	isDisconnecting: false,
+	error: null
+};
+/**
+* A custom hook that consumes `useWalletState` to get `walletFacadeHooks`,
+* then calls the `useDisconnect` facade hook (if available) and returns a structured,
+* safely-accessed status and control function for wallet disconnection.
+*/
+function useDerivedDisconnect() {
+	const { walletFacadeHooks } = useWalletState();
+	const disconnectHookOutput = walletFacadeHooks?.useDisconnect ? walletFacadeHooks.useDisconnect() : void 0;
+	if ((0, _openzeppelin_ui_utils.isRecordWithProperties)(disconnectHookOutput)) return {
+		disconnect: "disconnect" in disconnectHookOutput && typeof disconnectHookOutput.disconnect === "function" ? disconnectHookOutput.disconnect : defaultDisconnectStatus.disconnect,
+		isDisconnecting: "isPending" in disconnectHookOutput && typeof disconnectHookOutput.isPending === "boolean" ? disconnectHookOutput.isPending : "isLoading" in disconnectHookOutput && typeof disconnectHookOutput.isLoading === "boolean" ? disconnectHookOutput.isLoading : defaultDisconnectStatus.isDisconnecting,
+		error: "error" in disconnectHookOutput && disconnectHookOutput.error instanceof Error ? disconnectHookOutput.error : defaultDisconnectStatus.error
+	};
+	return defaultDisconnectStatus;
+}
+
+//#endregion
+//#region src/hooks/useWalletReconnectionHandler.ts
+/**
+* Hook that detects wallet reconnection and re-queues network switch if needed.
+*
+* When a user disconnects their wallet and then reconnects in the same session,
+* the wallet may connect to a different chain than what's selected in the app.
+* This hook detects that scenario and invokes a callback to re-queue the network switch.
+*
+* @param selectedNetworkConfigId - Currently selected network in the app
+* @param selectedAdapter - Currently active adapter instance
+* @param networkToSwitchTo - Current network switch queue state (null if no switch pending)
+* @param onRequeueSwitch - Callback invoked when a network switch should be re-queued
+*/
+function useWalletReconnectionHandler(selectedNetworkConfigId, selectedAdapter, networkToSwitchTo, onRequeueSwitch) {
+	const { isConnected, chainId: walletChainId } = useDerivedAccountStatus();
+	const prevConnectedRef = (0, react.useRef)(isConnected);
+	(0, react.useEffect)(() => {
+		const isReconnection = !prevConnectedRef.current && isConnected;
+		prevConnectedRef.current = isConnected;
+		if (!isReconnection || !selectedNetworkConfigId || !selectedAdapter) return;
+		if (networkToSwitchTo === selectedNetworkConfigId) return;
+		const adapterConfig = selectedAdapter.networkConfig;
+		if (!("chainId" in adapterConfig) || !walletChainId) return;
+		const targetChainId = Number(adapterConfig.chainId);
+		if (walletChainId !== targetChainId) {
+			_openzeppelin_ui_utils.logger.info("useWalletReconnectionHandler", `Wallet reconnected with chain ${walletChainId}, but selected network requires ${targetChainId}. Re-queueing switch.`);
+			onRequeueSwitch(selectedNetworkConfigId);
+		}
+	}, [
+		isConnected,
+		walletChainId,
+		selectedNetworkConfigId,
+		selectedAdapter,
+		networkToSwitchTo,
+		onRequeueSwitch
+	]);
+}
+
+//#endregion
+//#region src/components/WalletConnectionUI.tsx
+/**
+* Component that displays wallet connection UI components
+* provided by the active adapter.
+*/
+const WalletConnectionUI = ({ className }) => {
+	const [isError, setIsError] = (0, react.useState)(false);
+	const { activeAdapter, walletFacadeHooks } = useWalletState();
+	(0, react.useEffect)(() => {
+		_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "[Debug] State from useWalletState:", {
+			adapterId: activeAdapter?.networkConfig.id,
+			hasFacadeHooks: !!walletFacadeHooks
+		});
+	}, [activeAdapter, walletFacadeHooks]);
+	const walletComponents = (() => {
+		if (!activeAdapter || typeof activeAdapter.getEcosystemWalletComponents !== "function") {
+			_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "[Debug] No activeAdapter or getEcosystemWalletComponents method, returning null.");
+			return null;
+		}
+		try {
+			const components = activeAdapter.getEcosystemWalletComponents();
+			_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "[Debug] walletComponents from adapter:", components);
+			return components;
+		} catch (error) {
+			_openzeppelin_ui_utils.logger.error("WalletConnectionUI", "[Debug] Error getting wallet components:", error);
+			setIsError(true);
+			return null;
+		}
+	})();
+	if (!walletComponents) {
+		_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "[Debug] getEcosystemWalletComponents returned null/undefined, rendering null.");
+		return null;
+	}
+	_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "Rendering wallet components:", {
+		hasConnectButton: !!walletComponents.ConnectButton,
+		hasAccountDisplay: !!walletComponents.AccountDisplay,
+		hasNetworkSwitcher: !!walletComponents.NetworkSwitcher
+	});
+	const { ConnectButton, AccountDisplay, NetworkSwitcher } = walletComponents;
+	if (isError) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+		className: (0, _openzeppelin_ui_utils.cn)("flex items-center gap-4", className),
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_openzeppelin_ui_components.Button, {
+			variant: "destructive",
+			size: "sm",
+			onClick: () => window.location.reload(),
+			children: "Wallet Error - Retry"
+		})
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: (0, _openzeppelin_ui_utils.cn)("flex items-center gap-4", className),
+		children: [
+			NetworkSwitcher && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(NetworkSwitcher, {}),
+			AccountDisplay && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AccountDisplay, {}),
+			ConnectButton && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ConnectButton, {})
+		]
+	});
+};
+
+//#endregion
+//#region src/components/WalletConnectionHeader.tsx
+/**
+* Component that renders the wallet connection UI.
+* Uses useWalletState to get its data.
+*/
+const WalletConnectionHeader = () => {
+	const { isAdapterLoading, activeAdapter } = useWalletState();
+	(0, react.useEffect)(() => {
+		_openzeppelin_ui_utils.logger.debug("WalletConnectionHeader", "[Debug] State from useWalletState:", {
+			adapterPresent: !!activeAdapter,
+			adapterNetwork: activeAdapter?.networkConfig.id,
+			isLoading: isAdapterLoading
+		});
+	}, [activeAdapter, isAdapterLoading]);
+	if (isAdapterLoading) {
+		_openzeppelin_ui_utils.logger.debug("WalletConnectionHeader", "[Debug] Adapter loading, showing skeleton.");
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { className: "h-9 w-28 animate-pulse rounded bg-muted" });
+	}
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(WalletConnectionUI, {});
+};
+
+//#endregion
+//#region src/components/NetworkSwitchManager.tsx
+/**
+* Component that handles wallet network switching based on the selected network.
+*
+* This component manages the lifecycle of network switching operations,
+* coordinating between the wallet's current chain state and the target network.
+* It's designed to be used in any application that needs seamless wallet network switching.
+*
+* Features:
+* - Automatically initiates network switch when mounted with a target network
+* - Handles EVM chain switching gracefully
+* - No-ops for non-EVM networks that don't support chain switching
+* - Tracks switch attempts to prevent duplicate operations
+* - Provides completion callback for parent components to handle state cleanup
+*/
+const NetworkSwitchManager = ({ adapter, targetNetworkId, onNetworkSwitchComplete }) => {
+	const isMountedRef = (0, react.useRef)(true);
+	const [hasAttemptedSwitch, setHasAttemptedSwitch] = (0, react.useState)(false);
+	const { isConnected, chainId: currentChainIdFromHook } = useDerivedAccountStatus();
+	const { switchChain: execSwitchNetwork, isSwitching: isSwitchingNetworkViaHook, error: switchNetworkError } = useDerivedSwitchChainStatus();
+	(0, react.useEffect)(() => {
+		isMountedRef.current = true;
+		_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", `Mounted with target: ${targetNetworkId}, current attempt status: ${hasAttemptedSwitch}`);
+		setHasAttemptedSwitch(false);
+		return () => {
+			_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", `Unmounting, was for target: ${targetNetworkId}`);
+			isMountedRef.current = false;
+		};
+	}, [targetNetworkId]);
+	(0, react.useEffect)(() => {
+		_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", "State Update:", {
+			target: targetNetworkId,
+			adapterNetwork: adapter.networkConfig.id,
+			isSwitching: isSwitchingNetworkViaHook,
+			hookError: !!switchNetworkError,
+			canExec: !!execSwitchNetwork,
+			connected: isConnected,
+			walletChain: currentChainIdFromHook,
+			attempted: hasAttemptedSwitch
+		});
+	}, [
+		adapter,
+		targetNetworkId,
+		isSwitchingNetworkViaHook,
+		switchNetworkError,
+		execSwitchNetwork,
+		isConnected,
+		currentChainIdFromHook,
+		hasAttemptedSwitch
+	]);
+	(0, react.useEffect)(() => {
+		const completeOperation = (logMessage, options = { notifyComplete: true }) => {
+			if (logMessage) _openzeppelin_ui_utils.logger.info("NetworkSwitchManager", logMessage);
+			if (options.notifyComplete && isMountedRef.current && onNetworkSwitchComplete) onNetworkSwitchComplete();
+			if (isMountedRef.current) setHasAttemptedSwitch(false);
+		};
+		if (!execSwitchNetwork) {
+			completeOperation("No switchChain function available from hook. Operation halted.", { notifyComplete: false });
+			return;
+		}
+		if (isSwitchingNetworkViaHook && hasAttemptedSwitch) {
+			_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", "Hook reports switch in progress for current attempt. Waiting...");
+			return;
+		}
+		if (hasAttemptedSwitch && !isSwitchingNetworkViaHook) {
+			_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", "Previous switch attempt concluded. Deferring to completion effect.");
+			return;
+		}
+		if (adapter.networkConfig.id !== targetNetworkId) {
+			completeOperation(`CRITICAL: Adapter (${adapter.networkConfig.id}) vs Target (${targetNetworkId}) mismatch. Operation halted.`, { notifyComplete: false });
+			return;
+		}
+		if (!isConnected) {
+			completeOperation("Wallet not connected (derived status). Awaiting connection.", { notifyComplete: false });
+			return;
+		}
+		if (!("chainId" in adapter.networkConfig)) {
+			completeOperation("Network does not support chain switching (non-EVM). Operation complete (no-op).");
+			return;
+		}
+		const targetChainToBeSwitchedTo = Number(adapter.networkConfig.chainId);
+		if (currentChainIdFromHook === targetChainToBeSwitchedTo) {
+			completeOperation("Already on correct chain (derived status). Operation complete.");
+			return;
+		}
+		const performSwitchActual = () => {
+			if (!isMountedRef.current || isSwitchingNetworkViaHook || hasAttemptedSwitch) {
+				_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", `Switch attempt aborted in timeout or already handled. Conditions: isSwitching: ${isSwitchingNetworkViaHook}, hasAttempted: ${hasAttemptedSwitch}`);
+				return;
+			}
+			_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", `Attempting switch to ${targetChainToBeSwitchedTo} via derived hook.`);
+			setHasAttemptedSwitch(true);
+			execSwitchNetwork({ chainId: targetChainToBeSwitchedTo });
+		};
+		const timeoutId = setTimeout(performSwitchActual, 100);
+		return () => clearTimeout(timeoutId);
+	}, [
+		adapter,
+		targetNetworkId,
+		execSwitchNetwork,
+		isSwitchingNetworkViaHook,
+		onNetworkSwitchComplete,
+		isConnected,
+		currentChainIdFromHook,
+		hasAttemptedSwitch
+	]);
+	(0, react.useEffect)(() => {
+		if (!isMountedRef.current || !execSwitchNetwork || !hasAttemptedSwitch) return;
+		if (!isSwitchingNetworkViaHook) {
+			let completionMessage = "Switch hook operation concluded.";
+			if (switchNetworkError) {
+				_openzeppelin_ui_utils.logger.error("NetworkSwitchManager", "Error from derived switch hook:", switchNetworkError);
+				completionMessage = "Switch hook completed with error.";
+			} else _openzeppelin_ui_utils.logger.info("NetworkSwitchManager", "Derived switch hook completed successfully.");
+			if (onNetworkSwitchComplete) onNetworkSwitchComplete();
+			if (isMountedRef.current) setHasAttemptedSwitch(false);
+			_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", completionMessage);
+		}
+	}, [
+		isSwitchingNetworkViaHook,
+		switchNetworkError,
+		execSwitchNetwork,
+		hasAttemptedSwitch,
+		onNetworkSwitchComplete
+	]);
+	return null;
+};
+
+//#endregion
+exports.AdapterContext = AdapterContext;
+exports.AdapterProvider = AdapterProvider;
+exports.AnalyticsContext = AnalyticsContext;
+exports.AnalyticsProvider = AnalyticsProvider;
+exports.NetworkSwitchManager = NetworkSwitchManager;
+exports.WalletConnectionHeader = WalletConnectionHeader;
+exports.WalletConnectionUI = WalletConnectionUI;
+exports.WalletStateContext = WalletStateContext;
+exports.WalletStateProvider = WalletStateProvider;
+exports.useAdapterContext = useAdapterContext;
+exports.useAnalytics = useAnalytics;
+exports.useDerivedAccountStatus = useDerivedAccountStatus;
+exports.useDerivedChainInfo = useDerivedChainInfo;
+exports.useDerivedConnectStatus = useDerivedConnectStatus;
+exports.useDerivedDisconnect = useDerivedDisconnect;
+exports.useDerivedSwitchChainStatus = useDerivedSwitchChainStatus;
+exports.useWalletReconnectionHandler = useWalletReconnectionHandler;
+exports.useWalletState = useWalletState;
+//# sourceMappingURL=index.cjs.map