@tuwaio/nova-connect 1.0.0-fix-test-alpha.55.f5b462c → 1.0.0-fix-test-alpha.56.a984de3

package/dist/providers/index.d.cts

@@ -1,8 +1,35 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ToastPosition } from 'react-toastify';
-import { ISatelliteConnectStore } from '@tuwaio/satellite-core';
+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';
-import { ReactNode } from 'react';
+
+/**
+ * @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
@@ -101,39 +128,217 @@ type NovaConnectLabels = {
     impersonateAddressConnected: string;
 };
 
-/**
- * @description
- * This interface is intentionally left empty.
- * Other packages (@tuwaio/satellite-*) will use module
- * augmentation to add their specific wallet types here.
- */
-interface AllWallets {
+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>;
 }
-/**
- * @description
- * This interface is intentionally left empty.
- * It will be augmented by satellite packages.
- */
-interface AllConnectors {
+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;
+    style?: React.CSSProperties;
+    'aria-hidden'?: boolean;
+};
+type CustomTitleProps = {
+    title: string;
+    titleId: string;
+    className?: string;
+    style?: React.CSSProperties;
+};
+type CustomDescriptionProps = {
+    rawError: string;
+    descriptionId: string;
+    className?: string;
+    style?: React.CSSProperties;
+};
+type CustomButtonContentProps = {
+    icon: ReactNode;
+    isCopied: boolean;
+    copyLabel: string;
+    copiedLabel: string;
+};
 /**
- * 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
+ * Customization options for ToastError component
  */
-type Wallet = AllWallets[keyof AllWallets];
+type ToastErrorCustomization = {
+    /** Override container element props */
+    containerProps?: Partial<ComponentPropsWithoutRef<'div'>>;
+    /** Override button element props */
+    buttonProps?: Partial<ComponentPropsWithoutRef<'button'>>;
+    /** 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 style generators */
+    styles?: {
+        /** Function to generate container styles */
+        container?: (params: {
+            hasTitle: boolean;
+            hasError: boolean;
+        }) => React.CSSProperties;
+        /** Function to generate title styles */
+        title?: (params: {
+            title: string;
+        }) => React.CSSProperties;
+        /** Function to generate description styles */
+        description?: (params: {
+            rawError: string;
+        }) => React.CSSProperties;
+        /** Function to generate button styles */
+        button?: (params: {
+            isCopied: boolean;
+            disabled: boolean;
+        }) => React.CSSProperties;
+        /** Function to generate icon styles */
+        icon?: (params: {
+            isCopied: boolean;
+        }) => React.CSSProperties;
+    };
+    /** 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>;
 /**
- * Union type for all supported connector types.
+ * Customization options for ErrorsProvider component
  */
-type Connector = AllConnectors[keyof AllConnectors];
-
-interface NovaConnectProviderProps {
-    store: StoreApi<ISatelliteConnectStore<Connector, Wallet>>;
-    children: React.ReactNode;
-    labels?: Partial<NovaConnectLabels>;
-}
-
-interface ErrorsProviderProps extends Pick<NovaConnectProviderProps, 'store'> {
+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 style generators */
+    styles?: {
+        /** Function to generate container styles */
+        container?: (params: {
+            hasErrors: boolean;
+            errorType: 'wallet' | 'switch' | null;
+        }) => React.CSSProperties;
+    };
+    /** 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 */
@@ -142,8 +347,14 @@ interface ErrorsProviderProps extends Pick<NovaConnectProviderProps, 'store'> {
     autoClose?: number | false;
     /** Whether to enable drag to dismiss */
     draggable?: boolean;
+    /** Customization options */
+    customization?: ErrorsProviderCustomization;
 }
-declare function ErrorsProvider({ store, containerId, position, autoClose, draggable, }: ErrorsProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * 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;
 }
@@ -185,6 +396,149 @@ declare namespace NovaConnectLabelsProvider {
     var displayName: string;
 }
 
-declare function NovaConnectProvider({ labels, store, children }: NovaConnectProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * 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, NovaConnectLabelsProvider, NovaConnectProvider };
+export { ErrorsProvider, type ErrorsProviderCustomization, type ErrorsProviderProps, NovaConnectLabelsProvider, NovaConnectProvider, type NovaConnectProviderCustomization, type NovaConnectProviderProps };