@openzeppelin/ui-react 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,421 @@
+import * as react0 from "react";
+import React, { ReactNode } from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { Connector, ContractAdapter, EcosystemSpecificReactHooks, NativeConfigLoader, NetworkConfig, UiKitConfiguration } from "@openzeppelin/ui-types";
+
+//#region src/hooks/AdapterContext.d.ts
+/**
+ * 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: react0.Context<AdapterContextValue | null>;
+//# sourceMappingURL=AdapterContext.d.ts.map
+//#endregion
+//#region src/hooks/AdapterProvider.d.ts
+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_runtime0.JSX.Element;
+//# sourceMappingURL=AdapterProvider.d.ts.map
+//#endregion
+//#region src/hooks/WalletStateContext.d.ts
+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.Context<WalletStateContextValue | undefined>;
+/**
+ * Hook to access wallet state from WalletStateProvider.
+ * @throws Error if used outside of WalletStateProvider
+ */
+declare function useWalletState(): WalletStateContextValue;
+//# sourceMappingURL=WalletStateContext.d.ts.map
+//#endregion
+//#region src/hooks/WalletStateProvider.d.ts
+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_runtime0.JSX.Element;
+//# sourceMappingURL=WalletStateProvider.d.ts.map
+//#endregion
+//#region src/hooks/AnalyticsContext.d.ts
+/**
+ * Analytics context value interface.
+ * Provides access to analytics functionality throughout the React component tree.
+ */
+interface AnalyticsContextValue {
+  /** Google Analytics tag ID */
+  tagId?: string;
+  /**
+   * Check if analytics is enabled via feature flag.
+   * Returns fresh state on each call to handle dynamic feature flag changes.
+   */
+  isEnabled: () => boolean;
+  /** Initialize analytics with optional tag ID override */
+  initialize: (tagIdOverride?: string) => void;
+  /**
+   * Track a generic event with custom parameters.
+   * Use this for app-specific events.
+   *
+   * @example
+   * ```typescript
+   * trackEvent('button_clicked', { button_name: 'submit' });
+   * ```
+   */
+  trackEvent: (eventName: string, parameters: Record<string, string | number>) => void;
+  /**
+   * Track page view event.
+   *
+   * @example
+   * ```typescript
+   * trackPageView('Dashboard', '/dashboard');
+   * ```
+   */
+  trackPageView: (pageName: string, pagePath: string) => void;
+  /**
+   * Track network selection event.
+   *
+   * @example
+   * ```typescript
+   * trackNetworkSelection('ethereum-mainnet', 'evm');
+   * ```
+   */
+  trackNetworkSelection: (networkId: string, ecosystem: string) => void;
+}
+/**
+ * Analytics context for providing analytics functionality to React components.
+ * Must be used within an AnalyticsProvider.
+ */
+declare const AnalyticsContext: react0.Context<AnalyticsContextValue | null>;
+/**
+ * Internal hook to access analytics context.
+ * Throws an error if used outside of an AnalyticsProvider.
+ *
+ * @internal
+ * @throws Error if used outside of AnalyticsProvider
+ */
+//#endregion
+//#region src/hooks/AnalyticsProvider.d.ts
+/**
+ * Props for the AnalyticsProvider component
+ */
+interface AnalyticsProviderProps {
+  /** Google Analytics tag ID (e.g., 'G-XXXXXXXXXX') */
+  tagId?: string;
+  /** Whether to automatically initialize analytics on mount (default: true) */
+  autoInit?: boolean;
+  /** Child components */
+  children: ReactNode;
+}
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare const AnalyticsProvider: React.FC<AnalyticsProviderProps>;
+//# sourceMappingURL=AnalyticsProvider.d.ts.map
+
+//#endregion
+//#region src/hooks/useAnalytics.d.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
+ */
+declare const useAnalytics: () => AnalyticsContextValue;
+//# sourceMappingURL=useAnalytics.d.ts.map
+//#endregion
+//#region src/hooks/useAdapterContext.d.ts
+/**
+ * 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;
+//# sourceMappingURL=useAdapterContext.d.ts.map
+//#endregion
+//#region src/hooks/useDerivedAccountStatus.d.ts
+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;
+//# sourceMappingURL=useDerivedAccountStatus.d.ts.map
+//#endregion
+//#region src/hooks/useDerivedSwitchChainStatus.d.ts
+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;
+//# sourceMappingURL=useDerivedSwitchChainStatus.d.ts.map
+//#endregion
+//#region src/hooks/useDerivedChainInfo.d.ts
+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;
+//# sourceMappingURL=useDerivedChainInfo.d.ts.map
+//#endregion
+//#region src/hooks/useDerivedConnectStatus.d.ts
+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;
+//# sourceMappingURL=useDerivedConnectStatus.d.ts.map
+//#endregion
+//#region src/hooks/useDerivedDisconnect.d.ts
+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;
+//# sourceMappingURL=useDerivedDisconnect.d.ts.map
+//#endregion
+//#region src/hooks/useWalletReconnectionHandler.d.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
+ */
+declare function useWalletReconnectionHandler(selectedNetworkConfigId: string | null, selectedAdapter: ContractAdapter | null, networkToSwitchTo: string | null, onRequeueSwitch: (networkId: string) => void): void;
+//# sourceMappingURL=useWalletReconnectionHandler.d.ts.map
+//#endregion
+//#region src/components/WalletConnectionHeader.d.ts
+/**
+ * Component that renders the wallet connection UI.
+ * Uses useWalletState to get its data.
+ */
+declare const WalletConnectionHeader: React.FC;
+//# sourceMappingURL=WalletConnectionHeader.d.ts.map
+//#endregion
+//#region src/components/WalletConnectionUI.d.ts
+interface WalletConnectionUIProps {
+  className?: string;
+}
+/**
+ * Component that displays wallet connection UI components
+ * provided by the active adapter.
+ */
+declare const WalletConnectionUI: React.FC<WalletConnectionUIProps>;
+//#endregion
+//#region src/components/NetworkSwitchManager.d.ts
+/**
+ * Props for the NetworkSwitchManager component.
+ */
+interface NetworkSwitchManagerProps {
+  /** The adapter instance for the target network */
+  adapter: ContractAdapter;
+  /** The network ID we want to switch to */
+  targetNetworkId: string;
+  /** Callback when network switch completes (success or error) */
+  onNetworkSwitchComplete?: () => void;
+}
+/**
+ * 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
+ */
+declare const NetworkSwitchManager: React.FC<NetworkSwitchManagerProps>;
+//# sourceMappingURL=NetworkSwitchManager.d.ts.map
+
+//#endregion
+export { AdapterContext, type AdapterContextValue, AdapterProvider, type AdapterProviderProps, type AdapterRegistry, AnalyticsContext, type AnalyticsContextValue, AnalyticsProvider, type AnalyticsProviderProps, type DerivedAccountStatus, type DerivedChainInfo, type DerivedConnectStatus, type DerivedDisconnectStatus, type DerivedSwitchChainStatus, NetworkSwitchManager, type NetworkSwitchManagerProps, WalletConnectionHeader, WalletConnectionUI, WalletStateContext, type WalletStateContextValue, WalletStateProvider, type WalletStateProviderProps, useAdapterContext, useAnalytics, useDerivedAccountStatus, useDerivedChainInfo, useDerivedConnectStatus, useDerivedDisconnect, useDerivedSwitchChainStatus, useWalletReconnectionHandler, useWalletState };
+//# sourceMappingURL=index-B_dOGVNW.d.ts.map