@tuwaio/nova-connect 0.1.0

package/dist/providers/index.d.ts

@@ -0,0 +1,506 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentPropsWithoutRef, ComponentType, ReactNode } from 'react';
+import { ToastContainer, toast, ToastPosition } from 'react-toastify';
+import { OrbitAdapter } from '@tuwaio/orbit-core';
+import { ISatelliteConnectStore, BaseWallet } from '@tuwaio/satellite-core';
+import { StoreApi } from 'zustand/index';
+
+/**
+ * @description
+ * This interface is intentionally left empty.
+ * Other packages (@tuwaio/satellite-*) will use module
+ * augmentation to add their specific wallet types here.
+ */
+interface AllWallets {
+}
+/**
+ * @description
+ * This interface is intentionally left empty.
+ * It will be augmented by satellite packages.
+ */
+interface AllConnectors {
+}
+/**
+ * Union type for all supported wallet types.
+ * It's created from the values of the AllWallets interface.
+ * e.g., { evm: EVMWallet, solana: SolanaWallet } -> EVMWallet | SolanaWallet
+ */
+type Wallet = AllWallets[keyof AllWallets];
+/**
+ * Union type for all supported connector types.
+ */
+type Connector = AllConnectors[keyof AllConnectors];
+
+/**
+ * Type definitions for NovaConnect component translations
+ * Contains all text strings for multi-language support
+ */
+type NovaConnectLabels = {
+    connectWallet: string;
+    disconnect: string;
+    connecting: string;
+    connected: string;
+    tryAgain: string;
+    back: string;
+    connect: string;
+    close: string;
+    all: string;
+    connectionError: string;
+    connectedSuccessfully: string;
+    connectingTo: string;
+    walletConnectionError: string;
+    errorWhenChainSwitching: string;
+    cannotConnectWallet: string;
+    success: string;
+    error: string;
+    replaced: string;
+    recent: string;
+    transactionLoading: string;
+    transactionSuccess: string;
+    transactionError: string;
+    transactionReplaced: string;
+    aboutWallets: string;
+    getWallet: string;
+    connectImpersonatedWallet: string;
+    transactionsInApp: string;
+    switchNetwork: string;
+    switchNetworks: string;
+    connectingEllipsis: string;
+    installed: string;
+    popular: string;
+    impersonate: string;
+    readOnlyMode: string;
+    whatIsWallet: string;
+    walletDescription: string;
+    whatIsNetwork: string;
+    networkDescription: string;
+    learnMore: string;
+    listOfNetworks: string;
+    viewOnExplorer: string;
+    viewTransactions: string;
+    enterWalletAddress: string;
+    walletAddressPlaceholder: string;
+    noConnectorsFound: string;
+    noConnectorsDescription: string;
+    somethingWentWrong: string;
+    networkPickingError: string;
+    pulsarAdapterRequired: string;
+    pulsarAdapterDescription: string;
+    selectAvailableNetwork: string;
+    startExploringWeb3: string;
+    walletKeyToDigitalWorld: string;
+    iDontHaveWallet: string;
+    choseWallet: string;
+    keyToNewInternet: string;
+    keyToNewInternetDescription: string;
+    logInWithoutHassle: string;
+    logInWithoutHassleDescription: string;
+    copyRawError: string;
+    copied: string;
+    chainSelector: string;
+    closeModal: string;
+    selectChain: string;
+    chainOption: string;
+    openChainSelector: string;
+    currentChain: string;
+    scrollToTop: string;
+    scrollToBottom: string;
+    chainListContainer: string;
+    walletControls: string;
+    openWalletModal: string;
+    walletConnected: string;
+    walletNotConnected: string;
+    walletBalance: string;
+    walletAddress: string;
+    transactionStatus: string;
+    successIcon: string;
+    errorIcon: string;
+    replacedIcon: string;
+    statusIcon: string;
+    loading: string;
+    idle: string;
+    unknownWallet: string;
+    walletAvatar: string;
+    ensAvatar: string;
+    walletIcon: string;
+    impersonateAddressEmpty: string;
+    impersonateAddressNotCorrect: string;
+    impersonateAddressConnected: string;
+};
+
+type ButtonTxStatus = 'idle' | 'loading' | 'succeed' | 'failed' | 'replaced';
+type ConnectContentType = 'network' | 'connectors' | 'about' | 'getWallet' | 'connecting' | 'impersonate';
+type ConnectedContentType = 'main' | 'transactions' | 'chains';
+interface NovaConnectProviderProps$1 {
+    store: StoreApi<ISatelliteConnectStore<Connector, Wallet>>;
+    children: React.ReactNode;
+    labels?: Partial<NovaConnectLabels>;
+}
+interface NovaConnectProviderType {
+    activeWallet: BaseWallet | undefined;
+    walletConnectionError: string | undefined;
+    isConnectModalOpen: boolean;
+    setIsConnectModalOpen: (value: boolean) => void;
+    isConnectedModalOpen: boolean;
+    setIsConnectedModalOpen: (value: boolean) => void;
+    isChainsListOpen: boolean;
+    setIsChainsListOpen: (value: boolean) => void;
+    isChainsListOpenMobile: boolean;
+    setIsChainsListOpenMobile: (value: boolean) => void;
+    connectedButtonStatus: ButtonTxStatus;
+    setConnectedButtonStatus: (value: ButtonTxStatus) => void;
+    isConnected: boolean;
+    setIsConnected: (value: boolean) => void;
+    connectedModalContentType: ConnectedContentType;
+    setConnectedModalContentType: (value: ConnectedContentType) => void;
+    connectModalContentType: ConnectContentType;
+    setConnectModalContentType: (value: ConnectContentType) => void;
+    selectedAdapter: OrbitAdapter | undefined;
+    setSelectedAdapter: (value: OrbitAdapter | undefined) => void;
+    activeConnector: string | undefined;
+    setActiveConnector: (value: string | undefined) => void;
+    impersonatedAddress: string;
+    setImpersonatedAddress: (value: string) => void;
+}
+
+type CustomIconProps = {
+    isCopied: boolean;
+    className?: string;
+    'aria-hidden'?: boolean;
+};
+type CustomTitleProps = {
+    title: string;
+    titleId: string;
+    className?: string;
+};
+type CustomDescriptionProps = {
+    rawError: string;
+    descriptionId: string;
+    className?: string;
+};
+type CustomButtonContentProps = {
+    icon: ReactNode;
+    isCopied: boolean;
+    copyLabel: string;
+    copiedLabel: string;
+};
+/**
+ * Customization options for ToastError component
+ */
+type ToastErrorCustomization = {
+    /** Override container element props */
+    containerProps?: Partial<Omit<ComponentPropsWithoutRef<'div'>, 'style'>>;
+    /** Override button element props */
+    buttonProps?: Partial<Omit<ComponentPropsWithoutRef<'button'>, 'style'>>;
+    /** Custom components */
+    components?: {
+        /** Custom icon component */
+        Icon?: ComponentType<CustomIconProps>;
+        /** Custom title component */
+        Title?: ComponentType<CustomTitleProps>;
+        /** Custom description component */
+        Description?: ComponentType<CustomDescriptionProps>;
+        /** Custom button content component */
+        ButtonContent?: ComponentType<CustomButtonContentProps>;
+    };
+    /** Custom class name generators */
+    classNames?: {
+        /** Function to generate container classes */
+        container?: (params: {
+            hasTitle: boolean;
+            hasError: boolean;
+        }) => string;
+        /** Function to generate title classes */
+        title?: (params: {
+            title: string;
+        }) => string;
+        /** Function to generate description classes */
+        description?: (params: {
+            rawError: string;
+        }) => string;
+        /** Function to generate button classes */
+        button?: (params: {
+            isCopied: boolean;
+            disabled: boolean;
+        }) => string;
+        /** Function to generate icon classes */
+        icon?: (params: {
+            isCopied: boolean;
+        }) => string;
+    };
+    /** Custom event handlers */
+    handlers?: {
+        /** Custom click handler wrapper */
+        onClick?: (originalHandler: (event: React.MouseEvent<HTMLButtonElement>) => void, event: React.MouseEvent<HTMLButtonElement>) => void;
+        /** Custom keydown handler wrapper */
+        onKeyDown?: (originalHandler: (event: React.KeyboardEvent<HTMLButtonElement>) => void, event: React.KeyboardEvent<HTMLButtonElement>) => void;
+    };
+};
+
+type CustomToastErrorProps = {
+    title: string;
+    rawError: string;
+    onCopyComplete?: (success: boolean) => void;
+    errorType: 'wallet' | 'switch' | null;
+    isConnected: boolean;
+};
+type CustomContainerProps = ComponentPropsWithoutRef<typeof ToastContainer>;
+/**
+ * Customization options for ErrorsProvider component
+ */
+type ErrorsProviderCustomization = {
+    /** Override ToastContainer element props */
+    containerProps?: Partial<ComponentPropsWithoutRef<typeof ToastContainer>>;
+    /** Custom components */
+    components?: {
+        /** Custom ToastError component */
+        ToastError?: ComponentType<CustomToastErrorProps>;
+        /** Custom ToastContainer component */
+        Container?: ComponentType<CustomContainerProps>;
+    };
+    /** Default ToastError customization (only used with default ToastError component) */
+    toastErrorCustomization?: ToastErrorCustomization;
+    /** Custom class name generators */
+    classNames?: {
+        /** Function to generate container classes */
+        container?: (params: {
+            hasErrors: boolean;
+            errorType: 'wallet' | 'switch' | null;
+        }) => string;
+    };
+    /** Custom toast options generators */
+    toastOptions?: {
+        /** Function to generate toast options */
+        error?: (params: {
+            title: string;
+            rawError: string;
+            errorType: 'wallet' | 'switch' | null;
+            isConnected: boolean;
+        }) => Partial<Parameters<typeof toast.error>[1]>;
+    };
+    /** Custom logic handlers */
+    handlers?: {
+        /** Custom error display logic */
+        showError?: (originalHandler: (title: string, rawError: string, errorKey: string) => void, params: {
+            title: string;
+            rawError: string;
+            errorKey: string;
+            errorType: 'wallet' | 'switch' | null;
+        }) => void;
+        /** Custom error dismissal logic */
+        dismissError?: (originalHandler: () => void) => void;
+        /** Custom copy complete handler */
+        onCopyComplete?: (success: boolean, rawError: string, errorType: 'wallet' | 'switch' | null) => void;
+    };
+    /** Custom error title generator - does NOT customize labels, just allows title modification */
+    errorTitle?: (defaultTitle: string, params: {
+        errorType: 'wallet' | 'switch' | null;
+    }) => string;
+    /** Custom error hash generator for deduplication */
+    errorHash?: (defaultHash: string | null, params: {
+        primaryError: string | null;
+        errorType: 'wallet' | 'switch' | null;
+    }) => string | null;
+};
+interface ErrorsProviderProps extends Pick<NovaConnectProviderProps$1, 'store'> {
+    /** Custom container ID for toast notifications */
+    containerId?: string;
+    /** Custom position for toast notifications */
+    position?: ToastPosition;
+    /** Auto close delay in milliseconds */
+    autoClose?: number | false;
+    /** Whether to enable drag to dismiss */
+    draggable?: boolean;
+    /** Customization options */
+    customization?: ErrorsProviderCustomization;
+}
+/**
+ * A highly customizable error toast provider with extensive styling options and component replacement capabilities.
+ * Provides comprehensive customization for appearance, behavior, and error handling logic while maintaining accessibility.
+ */
+declare function ErrorsProvider({ store, containerId, position, autoClose, draggable, customization, }: ErrorsProviderProps): react_jsx_runtime.JSX.Element;
+declare namespace ErrorsProvider {
+    var displayName: string;
+}
+
+interface NovaConnectLabelsProviderProps {
+    /** An object containing the custom labels */
+    labels: NovaConnectLabels;
+    /** The child components to render */
+    children: ReactNode;
+}
+/**
+ * A React component that provides a custom set of labels to all child components.
+ * Wrap your application or component tree with this provider to apply custom translations.
+ *
+ * The provider uses React.memo optimization and validates labels in development mode.
+ *
+ * @example
+ * ```typescript
+ * import { NovaConnectLabelsProvider } from './NovaConnectLabelsProvider';
+ *
+ * function App() {
+ *   const customLabels = {
+ *     connectWallet: 'Подключить кошелек',
+ *     disconnect: 'Отключиться',
+ *   };
+ *
+ *   return (
+ *     <NovaConnectLabelsProvider labels={customLabels}>
+ *       <YourApp />
+ *     </NovaConnectLabelsProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function NovaConnectLabelsProvider({ labels, children }: NovaConnectLabelsProviderProps): react_jsx_runtime.JSX.Element;
+declare namespace NovaConnectLabelsProvider {
+    var displayName: string;
+}
+
+/**
+ * Props for custom NovaConnectLabelsProvider component
+ */
+type CustomLabelsProviderProps = {
+    labels?: Partial<NovaConnectLabels>;
+    children: ReactNode;
+};
+/**
+ * Props for custom ErrorsProvider component
+ */
+type CustomErrorsProviderProps = Pick<ErrorsProviderProps, 'store'> & {
+    customization?: ErrorsProviderCustomization;
+};
+/**
+ * Context data passed to custom provider components
+ */
+type ProviderContext = {
+    /** Current wallet connection state */
+    isConnected: boolean;
+    /** Active wallet instance */
+    activeWallet: BaseWallet | undefined;
+    /** Current wallet connection error */
+    walletConnectionError: string | undefined;
+    /** All modal and UI states */
+    modalStates: {
+        isConnectModalOpen: boolean;
+        isConnectedModalOpen: boolean;
+        isChainsListOpen: boolean;
+        isChainsListOpenMobile: boolean;
+    };
+    /** Current content types for modals */
+    contentTypes: {
+        connectModal: ConnectContentType;
+        connectedModal: ConnectedContentType;
+    };
+    /** Button and transaction statuses */
+    statuses: {
+        connectedButton: ButtonTxStatus;
+    };
+};
+/**
+ * Comprehensive customization options for NovaConnectProvider
+ */
+type NovaConnectProviderCustomization = {
+    /** Custom components */
+    components?: {
+        /** Custom labels provider component */
+        LabelsProvider?: ComponentType<CustomLabelsProviderProps>;
+        /** Custom errors provider component */
+        ErrorsProvider?: ComponentType<CustomErrorsProviderProps>;
+    };
+    /** Labels customization and merging strategy */
+    labels?: {
+        /** Custom labels merging function */
+        merge?: (defaultLabels: NovaConnectLabels, userLabels: Partial<NovaConnectLabels>) => NovaConnectLabels;
+        /** Transform final merged labels before use */
+        transform?: (mergedLabels: NovaConnectLabels, context: ProviderContext) => NovaConnectLabels;
+    };
+    /** ErrorsProvider customization - passed through to ErrorsProvider */
+    errors?: ErrorsProviderCustomization;
+    /** Custom initialization logic */
+    initialization?: {
+        /** Custom logic after store subscription setup */
+        onStoreSubscribed?: (context: ProviderContext) => void;
+        /** Custom logic when connection state changes */
+        onConnectionStateChange?: (isConnected: boolean, activeWallet: BaseWallet | undefined, context: ProviderContext) => void;
+        /** Custom logic when error state changes */
+        onErrorStateChange?: (error: string | undefined, context: ProviderContext) => void;
+    };
+    /** Custom context value transformation */
+    contextValue?: {
+        /** Transform context value before providing to children */
+        transform?: (defaultValue: NovaConnectProviderType, context: ProviderContext) => NovaConnectProviderType;
+    };
+    /** Custom rendering logic */
+    rendering?: {
+        /** Custom provider tree structure */
+        providerTree?: (defaultTree: ReactNode, components: {
+            ErrorsProvider: ReactNode;
+            LabelsProvider: ReactNode;
+            MainContent: ReactNode;
+        }, context: ProviderContext) => ReactNode;
+    };
+};
+/**
+ * Extended props for NovaConnectProvider with full customization capabilities
+ */
+interface NovaConnectProviderProps extends NovaConnectProviderProps$1 {
+    /** Comprehensive customization options for the provider and its sub-components */
+    customization?: NovaConnectProviderCustomization;
+}
+/**
+ * Main NovaConnect provider component with comprehensive customization capabilities.
+ *
+ * This provider manages wallet connection state, error handling, internationalization,
+ * and modal states while offering extensive customization options for all sub-components
+ * and behaviors.
+ *
+ * Features:
+ * - Complete wallet connection state management
+ * - Customizable error handling through ErrorsProvider
+ * - Flexible internationalization system
+ * - Modal and UI state coordination
+ * - Extensive customization API for all aspects
+ * - Custom component replacement capabilities
+ * - Advanced initialization and lifecycle hooks
+ *
+ * @example Basic usage
+ * ```tsx
+ * <NovaConnectProvider store={store}>
+ *   <App />
+ * </NovaConnectProvider>
+ * ```
+ *
+ * @example With customization
+ * ```tsx
+ * <NovaConnectProvider
+ *   store={store}
+ *   labels={customLabels}
+ *   customization={{
+ *     errors: {
+ *       position: 'bottom-right',
+ *       autoClose: 5000,
+ *       components: {
+ *         ToastError: CustomToastError
+ *       }
+ *     },
+ *     initialization: {
+ *       onConnectionStateChange: (isConnected, wallet) => {
+ *         console.log('Connection state:', isConnected, wallet);
+ *       }
+ *     }
+ *   }}
+ * >
+ *   <App />
+ * </NovaConnectProvider>
+ * ```
+ *
+ * @param props - Provider configuration and customization options
+ */
+declare function NovaConnectProvider({ labels, store, children, customization }: NovaConnectProviderProps): react_jsx_runtime.JSX.Element;
+declare namespace NovaConnectProvider {
+    var displayName: string;
+}
+
+export { ErrorsProvider, type ErrorsProviderCustomization, type ErrorsProviderProps, NovaConnectLabelsProvider, NovaConnectProvider, type NovaConnectProviderCustomization, type NovaConnectProviderProps };