@rango-dev/wallets-react 0.0.0-experimental-936229e8-20251208

package/src/legacy/hooks.ts

@@ -0,0 +1,54 @@
+import type { ProviderContext, WalletActions, WalletConfig } from './types.js';
+import type { LegacyEventHandler as WalletEventHandler } from '@rango-dev/wallets-core/legacy';
+
+import { LegacyWallet as Wallet } from '@rango-dev/wallets-core/legacy';
+import { useContext, useRef } from 'react';
+
+import { WalletContext } from './context.js';
+
+export type GetWalletInstance = (wallet: {
+  actions: WalletActions;
+  config: WalletConfig;
+}) => Wallet;
+
+export function useInitializers(
+  onChangeState: WalletEventHandler
+): GetWalletInstance {
+  const availableWallets = useRef<{
+    [key: string]: Wallet | undefined;
+  }>({});
+
+  /*
+   * If `wallet` hasn't been added to `availableWallets`,
+   * Get a instance of `Wallet` and save the refrence in `availableWallets`.
+   * Otherwise, return the already created instance.
+   */
+  function updater(wallet: {
+    actions: WalletActions;
+    config: WalletConfig;
+  }): Wallet {
+    const type = wallet.config.type;
+    // We only update, if there is no instance available.
+    if (typeof availableWallets.current[type] === 'undefined') {
+      availableWallets.current[type] = new Wallet(
+        {
+          config: wallet.config,
+          handler: onChangeState,
+        },
+        wallet.actions
+      );
+    }
+
+    return availableWallets.current[type]!;
+  }
+
+  return updater;
+}
+
+export function useWallets(): ProviderContext {
+  const context = useContext(WalletContext);
+  if (!context) {
+    throw Error('useWallet can only be used within the Provider component');
+  }
+  return context;
+}

package/src/legacy/mod.ts

@@ -0,0 +1,13 @@
+export type {
+  ProviderProps,
+  ProviderContext,
+  ConnectResult,
+  ExtendedWalletInfo,
+} from './types.js';
+export {
+  LEGACY_LAST_CONNECTED_WALLETS,
+  HUB_LAST_CONNECTED_WALLETS,
+} from '../hub/constants.js';
+
+export { WalletContext } from './context.js';
+export { useLegacyProviders } from './useLegacyProviders.js';

package/src/legacy/types.ts

@@ -0,0 +1,195 @@
+import type {
+  Provider,
+  ProviderMetadata,
+  VersionedProviders,
+} from '@rango-dev/wallets-core';
+import type {
+  LegacyNamespaceInputForConnect,
+  LegacyProviderInterface,
+  LegacyNetwork as Network,
+  LegacyEventHandler as WalletEventHandler,
+  LegacyWalletInfo as WalletInfo,
+  LegacyState as WalletState,
+  LegacyWalletType as WalletType,
+} from '@rango-dev/wallets-core/legacy';
+import type { Namespace } from '@rango-dev/wallets-core/namespaces/common';
+import type { NamespaceData } from '@rango-dev/wallets-core/store';
+import type { BlockchainMeta, SignerFactory } from 'rango-types';
+import type { PropsWithChildren } from 'react';
+
+import { LegacyEvents as Events } from '@rango-dev/wallets-core/legacy';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type InstanceType = any;
+
+export type State = {
+  [key: string]: WalletState | undefined;
+};
+
+export type ConnectResult = {
+  accounts: string[] | null;
+  network: Network | null;
+  provider: InstanceType;
+};
+
+export type Providers = { [type in WalletType]?: InstanceType };
+
+export type ExtendedWalletInfo = WalletInfo & {
+  properties?: ProviderMetadata['properties'];
+  isHub?: boolean;
+};
+
+export type ProviderContext = {
+  connect(
+    type: WalletType,
+    namespaces?: LegacyNamespaceInputForConnect[]
+  ): Promise<ConnectResult[]>;
+  disconnect(type: WalletType, namespaces?: Namespace[]): Promise<void>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  disconnectAll(): Promise<PromiseSettledResult<any>[]>;
+
+  state(
+    type: WalletType
+  ): WalletState & { namespaces?: Map<Namespace, NamespaceData> };
+  canSwitchNetworkTo(
+    type: WalletType,
+    network: Network,
+    namespace?: LegacyNamespaceInputForConnect
+  ): boolean;
+  /**
+   * `Provider` in legacy terms means injected instances by wallets into window (e.g. window.ethereum)
+   * that can be retrieved by `getInstance`.
+   *
+   * Note 1: Providers are lazy evaluated, which means you need to call `connect` (or `state`) first, then the value will be shown in object.
+   *         before doing that, it's a key (wallet name or we call it `type` to be more specific) with null value. (e.g. {metamask: null})
+   */
+  providers(): Providers;
+  getSigners(type: WalletType): Promise<SignerFactory>;
+  getWalletInfo(type: WalletType): ExtendedWalletInfo;
+  suggestAndConnect(type: WalletType, network: Network): Promise<ConnectResult>;
+  hubProvider(type: WalletType): Provider;
+};
+
+export type ProviderProps = PropsWithChildren<{
+  onUpdateState?: WalletEventHandler;
+  allBlockChains?: BlockchainMeta[];
+  autoConnect?: boolean;
+  providers: VersionedProviders[];
+  configs?: {
+    wallets?: (WalletType | LegacyProviderInterface | Provider)[];
+  };
+}>;
+
+export { Events };
+
+export type ProviderConnectResult = {
+  accounts: string[];
+  chainId: string;
+  derivationPath?: string;
+};
+
+export type GetInstanceOptions = {
+  network?: Network;
+  currentProvider: InstanceType;
+  meta: BlockchainMeta[];
+  getState: () => WalletState;
+  /**
+   * We always get the instance once and reuse it whenever we needs. By using this option
+   * We can force the library to get a new instance and replace it with the old one.
+   *
+   * Originally, we used this option for wallet connect 1 and its switching network challenge.
+   */
+  force?: boolean;
+  updateChainId: (chainId: number | string) => void;
+};
+
+export type GetInstance =
+  | (() => InstanceType)
+  | ((options: GetInstanceOptions) => Promise<InstanceType>);
+export type TryGetInstance =
+  | (() => InstanceType)
+  | ((
+      options: Pick<GetInstanceOptions, 'force' | 'network'>
+    ) => Promise<InstanceType>);
+export type Connect = (options: {
+  instance: InstanceType;
+  network?: Network;
+  meta: BlockchainMeta[];
+}) => Promise<ProviderConnectResult | ProviderConnectResult[]>;
+
+export type Disconnect = (options: {
+  instance: InstanceType;
+  destroyInstance: () => void;
+}) => Promise<void>;
+
+type CleanupSubscribe = () => void;
+
+export type Subscribe = (options: {
+  instance: InstanceType;
+  state: WalletState;
+  meta: BlockchainMeta[];
+  updateChainId: (chainId: string) => void;
+  updateAccounts: (accounts: string[], chainId?: string) => void;
+  connect: (network?: Network) => void;
+  disconnect: () => void;
+}) => CleanupSubscribe | void;
+
+export type SwitchNetwork = (options: {
+  instance: InstanceType;
+  network: Network;
+  meta: BlockchainMeta[];
+  newInstance?: TryGetInstance;
+  getState?: () => WalletState;
+  updateChainId: (chainId: string) => void;
+}) => Promise<void>;
+
+export type Suggest = (options: {
+  instance: InstanceType;
+  network: Network;
+  meta: BlockchainMeta[];
+}) => Promise<void>;
+
+export type CanSwitchNetwork = (options: {
+  network: Network;
+  meta: BlockchainMeta[];
+  provider: InstanceType;
+}) => boolean;
+
+export type CanEagerConnect = (options: {
+  instance: InstanceType;
+  meta: BlockchainMeta[];
+}) => Promise<boolean>;
+
+export interface WalletActions {
+  connect: Connect;
+  getInstance: InstanceType;
+  disconnect?: Disconnect;
+  subscribe?: Subscribe;
+  // unsubscribe, // coupled to subscribe.
+
+  // Optional, but should be provided at the same time.
+  suggest?: Suggest;
+  switchNetwork?: SwitchNetwork;
+  getSigners: (provider: InstanceType) => Promise<SignerFactory>;
+  canSwitchNetworkTo?: CanSwitchNetwork;
+  canEagerConnect?: CanEagerConnect;
+  getWalletInfo(allBlockChains: BlockchainMeta[]): WalletInfo;
+}
+
+export interface WalletConfig {
+  type: WalletType;
+  defaultNetwork?: Network;
+  checkInstallation?: boolean;
+  isAsyncInstance?: boolean;
+  isAsyncSwitchNetwork?: boolean;
+}
+
+export type WalletProviders = Map<
+  WalletType,
+  {
+    actions: WalletActions;
+    config: WalletConfig;
+  }
+>;
+
+export type ProviderInterface = { config: WalletConfig } & WalletActions;

package/src/legacy/useAutoConnect.ts

@@ -0,0 +1,23 @@
+import type { ProviderProps } from './types.js';
+
+import { useEffect, useRef } from 'react';
+
+import { shouldTryAutoConnect } from './utils.js';
+
+export function useAutoConnect(
+  props: Pick<ProviderProps, 'allBlockChains' | 'autoConnect'> & {
+    /**
+     * A function to run autoConnect on instances
+     */
+    autoConnectHandler: () => void;
+  }
+) {
+  const autoConnectInitiated = useRef(false);
+
+  useEffect(() => {
+    if (shouldTryAutoConnect(props) && !autoConnectInitiated.current) {
+      autoConnectInitiated.current = true;
+      props.autoConnectHandler();
+    }
+  }, [props.autoConnect, props.allBlockChains]);
+}

package/src/legacy/useLegacyProviders.ts

@@ -0,0 +1,241 @@
+import type { ProviderContext, ProviderProps } from './types.js';
+import type { LegacyProviderInterface } from '@rango-dev/wallets-core/legacy';
+import type { WalletType } from '@rango-dev/wallets-shared';
+
+import { useEffect, useReducer } from 'react';
+
+import { autoConnect } from './autoConnect.js';
+import {
+  availableWallets,
+  checkWalletProviders,
+  clearPersistance,
+  connectedWallets,
+  defaultWalletState,
+  makeEventHandler,
+  stateReducer,
+  tryPersistWallet,
+  tryRemoveWalletFromPersistance,
+} from './helpers.js';
+import { useInitializers } from './hooks.js';
+import { useAutoConnect } from './useAutoConnect.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ProviderType = any;
+
+export type LegacyProviderProps = Omit<ProviderProps, 'providers'> & {
+  providers: LegacyProviderInterface[];
+};
+
+export function useLegacyProviders(
+  props: LegacyProviderProps
+): ProviderContext {
+  const [providersState, dispatch] = useReducer(stateReducer, {});
+
+  // Get (or add) wallet instance (`provider`s will be wrapped in a `Wallet`)
+  const getWalletInstance = useInitializers(
+    makeEventHandler(dispatch, props.onUpdateState)
+  );
+
+  // Getting providers from props and put all of them in a `Map` with an appropriate interface.
+  const listOfProviders = props.providers;
+  const wallets = checkWalletProviders(listOfProviders);
+
+  useAutoConnect({
+    allBlockChains: props.allBlockChains,
+    autoConnect: props.autoConnect,
+    autoConnectHandler: async () => autoConnect(wallets, getWalletInstance),
+  });
+
+  // Final API we put in context and it will be available to use for users.
+  const api: ProviderContext = {
+    async connect(type, namespaces) {
+      const wallet = wallets.get(type);
+      if (!wallet) {
+        throw new Error(`You should add ${type} to provider first.`);
+      }
+
+      // Legacy providers doesn't implemented multiple namespaces, so it will always be one value.
+      let network = undefined;
+      if (namespaces && namespaces.length > 0) {
+        /*
+         * This may not be safe in cases there are two `network` for namespaces, the first one will be picked always.
+         * But since legacy provider only accepts one value, it shouldn't be happened when we are using legacy mode.
+         */
+        network = namespaces.find((ns) => !!ns.network)?.network;
+      }
+
+      const walletInstance = getWalletInstance(wallet);
+      const result = await walletInstance.connect(network, namespaces);
+      if (props.autoConnect) {
+        void tryPersistWallet({
+          type,
+          walletActions: wallet.actions,
+          getState: api.state,
+        });
+      }
+
+      return [result];
+    },
+    async disconnect(type) {
+      const wallet = wallets.get(type);
+      if (!wallet) {
+        throw new Error(`You should add ${type} to provider first.`);
+      }
+
+      const walletInstance = getWalletInstance(wallet);
+      await walletInstance.disconnect();
+      if (props.autoConnect) {
+        tryRemoveWalletFromPersistance({ type, walletActions: wallet.actions });
+      }
+    },
+    async disconnectAll() {
+      const disconnect_promises: Promise<void>[] = [];
+
+      /*
+       * When a wallet is initializing, a record will be added to `providersState`
+       * So we use them to know what wallet has been initialized then we need to
+       * filter connected wallets only.
+       */
+      connectedWallets(providersState).forEach((type) => {
+        const wallet = wallets.get(type);
+
+        if (wallet) {
+          const walletInstance = getWalletInstance(wallet);
+          disconnect_promises.push(walletInstance.disconnect());
+        }
+      });
+
+      if (props.autoConnect) {
+        clearPersistance();
+      }
+      return await Promise.allSettled(disconnect_promises);
+    },
+
+    async suggestAndConnect(type, network) {
+      const wallet = wallets.get(type);
+      if (!wallet) {
+        throw new Error(`You should add ${type} to provider first.`);
+      }
+      const walletInstance = getWalletInstance(wallet);
+      const result = await walletInstance.suggestAndConnect(network);
+
+      return result;
+    },
+
+    state(type) {
+      return providersState[type] || defaultWalletState;
+    },
+    canSwitchNetworkTo(type, network) {
+      const wallet = wallets.get(type);
+      if (!wallet) {
+        return false;
+      }
+
+      const walletInstance = getWalletInstance(wallet);
+      return walletInstance.canSwitchNetworkTo
+        ? walletInstance.canSwitchNetworkTo(network, walletInstance.provider)
+        : false;
+    },
+    providers() {
+      const providers: { [type in WalletType]?: ProviderType } = {};
+      availableWallets(providersState).forEach((type) => {
+        const wallet = wallets.get(type);
+        if (wallet) {
+          const walletInstance = getWalletInstance(wallet);
+          providers[type] = walletInstance.provider;
+        }
+      });
+
+      return providers;
+    },
+    getWalletInfo(type) {
+      const wallet = wallets.get(type);
+      if (!wallet) {
+        throw new Error(`You should add ${type} to provider first.`);
+      }
+
+      /*
+       * Get wallet info could be used in render methods to show wallets data
+       * So, addWalletRef method shouldn't be called in this method
+       */
+
+      return wallet.actions.getWalletInfo(props.allBlockChains || []);
+    },
+    async getSigners(type) {
+      const wallet = wallets.get(type);
+
+      if (!wallet) {
+        throw new Error(`You should add ${type} to provider first.`);
+      }
+      const walletInstance = getWalletInstance(wallet);
+      const provider = walletInstance.provider;
+      const result = walletInstance.getSigners(provider);
+
+      return result;
+    },
+    hubProvider() {
+      throw new Error('This method is not available on legacy providers.');
+    },
+  };
+
+  // Initialize instances
+  useEffect(() => {
+    wallets.forEach((wallet) => {
+      const walletInstance = getWalletInstance(wallet);
+      const runOnInit = () => {
+        if (walletInstance.onInit) {
+          walletInstance.onInit();
+        }
+      };
+
+      const initWhenPageIsReady = (event: Event) => {
+        if (
+          event.target &&
+          (event.target as Document).readyState === 'complete'
+        ) {
+          runOnInit();
+
+          document.removeEventListener('readystatechange', initWhenPageIsReady);
+        }
+      };
+
+      // Try to run, maybe it's ready.
+      runOnInit();
+
+      /*
+       * Try again when the page has been completely loaded.
+       * Some of wallets, take some time to be fully injected and loaded.
+       */
+      document.addEventListener('readystatechange', initWhenPageIsReady);
+    });
+  }, []);
+
+  // Setting supported blockchains on instances
+  useEffect(() => {
+    const allBlockChains = props.allBlockChains;
+    if (allBlockChains) {
+      wallets.forEach((wallet) => {
+        const walletInstance = getWalletInstance(wallet);
+        const walletInfo = walletInstance.getWalletInfo(
+          props.allBlockChains || []
+        );
+        walletInstance.setInfo({
+          supportedBlockchains: walletInfo.supportedChains,
+          isContractWallet: !!walletInfo.isContractWallet,
+        });
+      });
+    }
+  }, [props.allBlockChains]);
+
+  // Setting event handler on instances
+  useEffect(() => {
+    wallets.forEach((wallet) => {
+      const walletInstance = getWalletInstance(wallet);
+      walletInstance.setHandler(
+        makeEventHandler(dispatch, props.onUpdateState)
+      );
+    });
+  }, [props.onUpdateState]);
+
+  return api;
+}

package/src/legacy/utils.ts

@@ -0,0 +1,7 @@
+import type { ProviderProps } from './types.js';
+
+export function shouldTryAutoConnect(
+  props: Pick<ProviderProps, 'allBlockChains' | 'autoConnect'>
+): boolean {
+  return !!props.allBlockChains?.length && !!props.autoConnect;
+}

package/src/provider.tsx

@@ -0,0 +1,18 @@
+import type { ProviderProps } from './legacy/types.js';
+
+import React from 'react';
+
+import { WalletContext } from './legacy/context.js';
+import { useProviders } from './useProviders.js';
+
+function Provider(props: ProviderProps) {
+  const api = useProviders(props);
+
+  return (
+    <WalletContext.Provider value={api}>
+      {props.children}
+    </WalletContext.Provider>
+  );
+}
+
+export default Provider;

package/src/test-utils/env.ts

@@ -0,0 +1,10 @@
+const TEST_ENVIRONMENT_AGENT = 'HappyDOM/0.0.0';
+
+/**
+ * Detecting wether our code is running in a test environment or not.
+ *
+ * Note: This is only useful when HappyDOM or jsdom has been added to test runner.
+ */
+export function isRunningInTestEnvironmentWithDom(): boolean {
+  return navigator.userAgent.includes(TEST_ENVIRONMENT_AGENT);
+}