@openzeppelin/contracts-ui-builder-react-core/dist/index.d.cts

Core React context providers and hooks for the OpenZeppelin Contracts UI Builder.

import * as React from 'react';
import React__default, { ReactNode } from 'react';
import { NetworkConfig, ContractAdapter, EcosystemSpecificReactHooks, UiKitConfiguration, NativeConfigLoader, Connector } from '@openzeppelin/contracts-ui-builder-types';
import * as react_jsx_runtime from 'react/jsx-runtime';

/**
 * Registry type that maps network IDs to their corresponding adapter instances
 * This is the core data structure for the singleton pattern
 */
interface AdapterRegistry {
    [networkId: string]: ContractAdapter;
}
/**
 * Context value interface defining what's provided through the context
 * The main functionality is getAdapterForNetwork which either returns
 * an existing adapter or initiates loading of a new one
 */
interface AdapterContextValue {
    getAdapterForNetwork: (networkConfig: NetworkConfig | null) => {
        adapter: ContractAdapter | null;
        isLoading: boolean;
    };
}
/**
 * The React Context that provides adapter registry access throughout the app
 * Components can access this through the useAdapterContext hook
 */
declare const AdapterContext: React.Context<AdapterContextValue | null>;

interface AdapterProviderProps {
    children: ReactNode;
    /** Function to resolve/create an adapter instance for a given NetworkConfig. */
    resolveAdapter: (networkConfig: NetworkConfig) => Promise<ContractAdapter>;
}
/**
 * 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
 */
declare function AdapterProvider({ children, resolveAdapter }: AdapterProviderProps): react_jsx_runtime.JSX.Element;

interface WalletStateContextValue {
    activeNetworkId: string | null;
    setActiveNetworkId: (networkId: string | null) => void;
    activeNetworkConfig: NetworkConfig | null;
    activeAdapter: ContractAdapter | null;
    isAdapterLoading: boolean;
    walletFacadeHooks: EcosystemSpecificReactHooks | null;
    reconfigureActiveAdapterUiKit: (uiKitConfig?: Partial<UiKitConfiguration>) => void;
}
declare const WalletStateContext: React__default.Context<WalletStateContextValue | undefined>;
declare function useWalletState(): WalletStateContextValue;

interface WalletStateProviderProps {
    children: ReactNode;
    /** Optional initial network ID to set as active when the provider mounts. */
    initialNetworkId?: string | null;
    /** Function to retrieve a NetworkConfig object by its ID. */
    getNetworkConfigById: (networkId: string) => Promise<NetworkConfig | null | undefined> | NetworkConfig | null | undefined;
    /**
     * Optional generic function to load configuration modules by relative path.
     * The adapter is responsible for constructing the conventional path (e.g., './config/wallet/[kitName].config').
     * @param relativePath The conventional relative path to the configuration module.
     * @returns A Promise resolving to the configuration object (expected to have a default export) or null.
     */
    loadConfigModule?: NativeConfigLoader;
}
/**
 * @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>`.
 */
declare function WalletStateProvider({ children, initialNetworkId, getNetworkConfigById, loadConfigModule, }: WalletStateProviderProps): react_jsx_runtime.JSX.Element;

/**
 * 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
 */
declare function useAdapterContext(): AdapterContextValue;

interface DerivedAccountStatus {
    isConnected: boolean;
    address?: string;
    chainId?: number;
}
/**
 * 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.
 */
declare function useDerivedAccountStatus(): DerivedAccountStatus;

interface DerivedSwitchChainStatus {
    /** Function to initiate a network switch. Undefined if not available. */
    switchChain?: (args: {
        chainId: number;
    }) => void;
    /** True if a network switch is currently in progress. */
    isSwitching: boolean;
    /** Error object if the last switch attempt failed, otherwise null. */
    error: 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.
 */
declare function useDerivedSwitchChainStatus(): DerivedSwitchChainStatus;

interface DerivedChainInfo {
    /** The current chain ID reported by the wallet's active connection, if available. */
    currentChainId?: number;
    /** Array of chains configured in the underlying wallet library (e.g., wagmi). Type is any[] for generic compatibility. */
    availableChains: unknown[];
}
/**
 * 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.
 */
declare function useDerivedChainInfo(): DerivedChainInfo;

interface DerivedConnectStatus {
    /** Function to initiate a connection, usually takes a connector. Undefined if not available. */
    connect?: (args?: {
        connector?: Connector;
    }) => void;
    /** Array of available connectors. Type is any[] for broad compatibility until Connector type is fully generic here. */
    connectors: Connector[];
    /** True if a connection attempt is in progress. */
    isConnecting: boolean;
    /** Error object if the last connection attempt failed, otherwise null. */
    error: Error | null;
    /** The connector a connection is pending for, if any. */
    pendingConnector?: Connector;
}
/**
 * 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.
 */
declare function useDerivedConnectStatus(): DerivedConnectStatus;

interface DerivedDisconnectStatus {
    /** Function to initiate disconnection. Undefined if not available. */
    disconnect?: () => void | Promise<void>;
    /** True if a disconnection attempt is in progress (if hook provides this). */
    isDisconnecting: boolean;
    /** Error object if the last disconnection attempt failed (if hook provides this). */
    error: 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.
 */
declare function useDerivedDisconnect(): DerivedDisconnectStatus;

/**
 * Component that renders the wallet connection UI.
 * Uses useWalletState to get its data.
 */
declare const WalletConnectionHeader: React__default.FC;

interface WalletConnectionUIProps {
    className?: string;
}
/**
 * Component that displays wallet connection UI components
 * provided by the active adapter.
 */
declare const WalletConnectionUI: React__default.FC<WalletConnectionUIProps>;

/**
 * Enhanced wallet connection header with network settings menu.
 * Used in exported apps to provide access to RPC and Explorer configuration.
 */
declare const WalletConnectionWithSettings: React__default.FC;

export { AdapterContext, type AdapterContextValue, AdapterProvider, type AdapterProviderProps, type AdapterRegistry, type DerivedAccountStatus, type DerivedChainInfo, type DerivedConnectStatus, type DerivedDisconnectStatus, type DerivedSwitchChainStatus, WalletConnectionHeader, WalletConnectionUI, WalletConnectionWithSettings, WalletStateContext, type WalletStateContextValue, WalletStateProvider, type WalletStateProviderProps, useAdapterContext, useDerivedAccountStatus, useDerivedChainInfo, useDerivedConnectStatus, useDerivedDisconnect, useDerivedSwitchChainStatus, useWalletState };