@tonconnect/ui 2.0.0-beta.1 → 2.0.0-beta.10

package/README.md

@@ -103,38 +103,95 @@ or
 const walletsList = await TonConnectUI.getWallets();
 ```
 
-## Call connect
+## Open connect modal
 "TonConnect UI connect button" (which is added at `buttonRootId`) automatically handles clicks and calls connect.
 But you are still able to open "connect modal" programmatically, e.g. after click on your custom connect button.
 
 ```ts
-const connectedWallet = await tonConnectUI.connectWallet();
+await tonConnectUI.openModal();
 ```
 
-If there is an error while wallet connecting, `TonConnectUIError` or `TonConnectError` will be thrown depends on situation.
+This method opens the modal window and returns a promise that resolves after the modal window is opened.
+
+If there is an error while modal opening, `TonConnectUIError` or `TonConnectError` will be thrown depends on situation.
+
+## Close connect modal
+
+```ts
+tonConnectUI.closeModal();
+```
+
+This method closes the modal window.
+
+## Get current modal state
+
+This getter returns the current state of the modal window. The state will be an object with `status` and `closeReason` properties. The `status` can be either 'opened' or 'closed'. If the modal is closed, you can check the `closeReason` to find out the reason of closing.
+
+```ts
+const currentModalState = tonConnectUI.modalState;
+```
+
+## Subscribe to the modal window state changes
+To subscribe to the changes of the modal window state, you can use the `onModalStateChange` method. It returns a function which has to be called to unsubscribe.
+
+```js
+const unsubscribeModal = tonConnectUI.onModalStateChange(
+    (state: WalletsModalState) => {
+        // update state/reactive variables to show updates in the ui
+        // state.status will be 'opened' or 'closed'
+        // if state.status is 'closed', you can check state.closeReason to find out the reason
+    }
+);
+```
+
+Call `unsubscribeModal()` later to save resources when you don't need to listen for updates anymore.
+
+## Wallets Modal Control
+
+The `tonConnectUI` provides methods for managing the modal window, such as `openModal()`, `closeModal()` and other, which are designed for ease of use and cover most use cases.
+
+```typescript
+const { modal } = tonConnectUI;
+
+// Open and close the modal
+await modal.open();
+modal.close();
+
+// Get the current modal state
+const currentState = modal.state;
+
+// Subscribe and unsubscribe to modal state changes
+const unsubscribe = modal.onStateChange(state => { /* ... */ });
+unsubscribe();
+```
+
+While `tonConnectUI` internally delegates these calls to the `modal`, it is recommended to use the `tonConnectUI` methods for a more straightforward and consistent experience. The `modal` is exposed in case you need direct access to the modal window's state and behavior, but this should generally be avoided unless necessary.
 
 ## Get current connected Wallet and WalletInfo
 You can use special getters to read current connection state. Note that this getter only represents current value, so they are not reactive. 
-To react and handle wallet changes use `onStatusChange` mathod.
+To react and handle wallet changes use `onStatusChange` method.
 
 ```ts
-    const currentWallet = tonConnectUI.wallet;
-    const currentWalletInfo = tonConnectUI.walletInfo;
-    const currentAccount = tonConnectUI.account;
-    const currentIsConnectedStatus = tonConnectUI.connected;
+const currentWallet = tonConnectUI.wallet;
+const currentWalletInfo = tonConnectUI.walletInfo;
+const currentAccount = tonConnectUI.account;
+const currentIsConnectedStatus = tonConnectUI.connected;
 ```
 
 ## Subscribe to the connection status changes
-```js
+
+To subscribe to the changes of the connection status, you can use the `onStatusChange` method. It returns a function which has to be called to unsubscribe.
+
+```ts
 const unsubscribe = tonConnectUI.onStatusChange(
     walletAndwalletInfo => {
         // update state/reactive variables to show updates in the ui
     } 
 );
-
-// call `unsubscribe()` later to save resources when you don't need to listen for updates anymore.
 ```
 
+Call `unsubscribe()` later to save resources when you don't need to listen for updates anymore.
+
 ## Disconnect wallet
 Call to disconnect the wallet.
 
@@ -284,31 +341,51 @@ const result = await tonConnectUI.sendTransaction(defaultTx, {
 });
 ```
 
-## Use inside TWA (Telegram web app)
-TonConnect UI will work in TWA in the same way as in a regular website!
+## Use inside TMA (Telegram Mini Apps)
+TonConnect UI will work in TMA in the same way as in a regular website!
 Basically, no changes are required from the dApp's developers. The only thing you have to set is a dynamic return strategy.
 
-Currently, it is impossible for TWA-wallets to redirect back to previous opened TWA-dApp like native wallet-apps do.
-It means, that you need to specify the return strategy as a link to your TWA that will be only applied if the dApp is opened in TWA mode.
+Currently, it is impossible for TMA-wallets to redirect back to previous opened TMA-dApp like native wallet-apps do.
+It means, that you need to specify the return strategy as a link to your TMA that will be only applied if the dApp is opened in TMA mode.
 
 ```ts
 tonConnectUI.uiOptions = {
-        twaReturnUrl: 'https://t.me/durov'
-    };
+    twaReturnUrl: 'https://t.me/durov'
+};
 ```
 
-In other words,
+In other words, TonConnect UI will automatically handle the return strategy based on the environment. **The following pseudo-code demonstrates the internal logic of TonConnect UI**:
+
+> Please note that you **don't need to add this code to your dApp**. It's just an example of how TonConnect UI processes the return strategy internally.
+
 ```ts
-if (isLinkToTelegram()) {
+let finalReturnStrategy;
+
+// Determine if the provided link opens Telegram (using protocols tg:// or domain t.me).
+if (isLinkToTelegram('https://example.com')) {
+    // In the Telegram Mini Apps environment,
     if (isInTWA()) {
-        FINAL_RETURN_STRATEGY = actionsConfiguration.twaReturnUrl || actionsConfiguration.returnStrategy;
-    } else {
-        FINAL_RETURN_STRATEGY = 'none';
+        // preference is given to 'twaReturnUrl',
+        finalReturnStrategy = actionsConfiguration.twaReturnUrl;
+
+        // but if it's not set, fallback to 'returnStrategy'.
+        if (!finalReturnStrategy) {
+            finalReturnStrategy = actionsConfiguration.returnStrategy;
+        }
+    }
+    // If not in a TMA environment,
+    else {
+        // the return strategy is set to 'none'.
+        finalReturnStrategy = 'none';
     }
-} else {
-    FINAL_RETURN_STRATEGY = actionsConfiguration.returnStrategy;
+}
+// When the link does not open Telegram,
+else {
+    // use the predefined 'returnStrategy'.
+    finalReturnStrategy = actionsConfiguration.returnStrategy;
 }
 
+// Now, 'finalReturnStrategy' contains the correct strategy based on the link's destination and the dApp's environment.
 ```
 
 ## Detect end of the connection restoring process
@@ -639,3 +716,72 @@ tonConnectUI.onStatusChange(wallet => {
         }
     });
 ```
+
+# Troubleshooting
+
+## Android Back Handler
+
+If you encounter any issues with the Android back handler, such as modals not closing properly when the back button is pressed, or conflicts with `history.pushState()` if you are manually handling browser history in your application, you can disable the back handler by setting `enableAndroidBackHandler` to `false`:
+
+```ts
+const tonConnectUI = new TonConnectUI({
+    // ...
+    enableAndroidBackHandler: false
+});
+```
+
+This will disable the custom back button behavior on Android, and you can then handle the back button press manually in your application.
+
+While we do not foresee any problems arising with the Android back handler, but if you find yourself needing to disable it due to an issue, please describe the problem in on [GitHub Issues](https://github.com/ton-connect/sdk/issues), so we can assist you further.
+
+## Animations not working
+
+If you are experiencing issues with animations not working in your environment, it might be due to a lack of support for the Web Animations API. To resolve this issue, you can use the `web-animations-js` polyfill.
+
+### Using npm
+
+To install the polyfill, run the following command:
+
+```shell
+npm install web-animations-js
+```
+
+Then, import the polyfill in your project:
+
+```typescript
+import 'web-animations-js';
+```
+
+### Using CDN
+
+Alternatively, you can include the polyfill via CDN by adding the following script tag to your HTML:
+
+```html
+<script src="https://www.unpkg.com/web-animations-js@latest/web-animations.min.js"></script>
+```
+
+Both methods will provide a fallback implementation of the Web Animations API and should resolve the animation issues you are facing.
+
+## Warning about 'encoding' module in Next.js
+
+If you are using Next.js and see a warning similar to the following:
+
+```
+ ⚠ ./node_modules/node-fetch/lib/index.js
+Module not found: Can't resolve 'encoding' in '.../node_modules/node-fetch/lib'
+
+Import trace for requested module:
+./node_modules/node-fetch/lib/index.js
+./node_modules/@tonconnect/isomorphic-fetch/index.mjs
+./node_modules/@tonconnect/sdk/lib/esm/index.mjs
+./node_modules/@tonconnect/ui/lib/esm/index.mjs
+```
+
+Please note that this is just a warning and should not affect the functionality of your application. If you wish to suppress the warning, you have two options:
+
+1. (Recommended) Wait for us to remove the dependency on `@tonconnect/isomorphic-fetch` in future releases. This dependency will be removed when we drop support for Node.js versions below 18.
+
+2. (Optional) Install the `encoding` package, to resolve the warning:
+```shell
+npm install encoding
+```