From 5033be1a30f9d3833a01419c64655970c173d3ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9Cmlikhar=E2=80=9D?= <m.likhtar@pixelplex.io>
Date: Thu, 11 Jul 2024 15:22:45 +0300
Subject: [PATCH 1/2] improve react doc

---
 docs/develop/dapps/ton-connect/react.mdx | 278 ++++++++++++-----------
 1 file changed, 143 insertions(+), 135 deletions(-)

diff --git a/docs/develop/dapps/ton-connect/react.mdx b/docs/develop/dapps/ton-connect/react.mdx
index fcd0fcaf2d..43240ec729 100644
--- a/docs/develop/dapps/ton-connect/react.mdx
+++ b/docs/develop/dapps/ton-connect/react.mdx
@@ -39,12 +39,12 @@ Add the `TonConnectButton`. The TonConnect Button is a universal UI component fo
 
 ```tsx
 export const Header = () => {
-    return (
-        <header>
-            <span>My App with React UI</span>
-            <TonConnectButton />
-        </header>
-    );
+  return (
+    <header>
+      <span>My App with React UI</span>
+      <TonConnectButton />
+    </header>
+  );
 };
 ```
 
@@ -53,7 +53,29 @@ You can add className and style props to the button as well. Note that you canno
 <TonConnectButton className="my-button-class" style={{ float: "right" }}/>
 ```
 
-Moreover, you always can initiate the connection manually, using `useTonConnectUI` hook and [connectWallet](https://github.com/ton-connect/sdk/tree/main/packages/ui#call-connect) method.
+Moreover, you always can initiate the connection manually, using `useTonConnectUI` hook and `openModal` method (❗ Note that `connectWallet` method is deprecated ❗).
+
+```tsx
+export const Header = () => {
+  const [tonConnectUI, setOptions] = useTonConnectUI();
+  return (
+    <header>
+      <span>My App with React UI</span>
+      <button onClick={() => tonConnectUI.openModal()}>
+        Connect Wallet
+      </button>
+    </header>
+  );
+};
+```
+
+You can connect to a specific wallet using the `openSingleWalletModal` method:
+
+```tsx
+<button onClick={() => tonConnectUI.openSingleWalletModal('tonwallet)}>
+  Connect Wallet
+</button>
+```
 
 ### 4) Redirects
 
@@ -85,23 +107,23 @@ If you want to use some low-level TON Connect UI SDK features in your React app,
 
 ### useTonAddress
 
-Use it to get user's current ton wallet address. Pass boolean parameter isUserFriendly to choose format of the address. If wallet is not connected hook will return empty string.
+Use it to get user's current ton wallet address. Pass the boolean parameter `isUserFriendly` (default is `true`) to choose the format of the address. If the wallet is not connected, the hook will return an empty string.
 
 ```tsx
 import { useTonAddress } from '@tonconnect/ui-react';
 
 export const Address = () => {
-    const userFriendlyAddress = useTonAddress();
-    const rawAddress = useTonAddress(false);
-
-    return (
-        userFriendlyAddress && (
-            <div>
-                <span>User-friendly address: {userFriendlyAddress}</span>
-                <span>Raw address: {rawAddress}</span>
-            </div>
-        )
-    );
+  const userFriendlyAddress = useTonAddress();
+  const rawAddress = useTonAddress(false);
+
+  return (
+    userFriendlyAddress && (
+      <div>
+        <span>User-friendly address: {userFriendlyAddress}</span>
+        <span>Raw address: {rawAddress}</span>
+      </div>
+    )
+  );
 };
 ```
 
@@ -109,26 +131,29 @@ export const Address = () => {
 
 Use it to get user's current ton wallet. If wallet is not connected hook will return null.
 
-See all wallet's properties
+See all wallet's properties:
 
 [Wallet interface](https://ton-connect.github.io/sdk/interfaces/_tonconnect_sdk.Wallet.html)
+
 [WalletInfo interface](https://ton-connect.github.io/sdk/types/_tonconnect_sdk.WalletInfo.html)
 
 ```tsx
 import { useTonWallet } from '@tonconnect/ui-react';
 
 export const Wallet = () => {
-    const wallet = useTonWallet();
-
-    return (
-        wallet && (
-            <div>
-                <span>Connected wallet: {wallet.name}</span>
-                <span>Device: {wallet.device.appName}</span>
-            </div>
-        )
-    );
+  const wallet = useTonWallet();
+
+  return (
+    wallet && (
+      <div>
+        <span>Connected wallet address: {wallet.account.address}</span>
+        <span>Device: {wallet.device.appName}</span>
+        <span>Connected via: {wallet.provider}</span>
+      </div>
+    )
+  );
 };
+
 ```
 
 ### useTonConnectUI
@@ -144,27 +169,21 @@ Use it to get access to the `TonConnectUI` instance and UI options updating func
 import { Locales, useTonConnectUI } from '@tonconnect/ui-react';
 
 export const Settings = () => {
-    const [tonConnectUI, setOptions] = useTonConnectUI();
-
-    const onLanguageChange = (lang: string) => {
-        setOptions({ language: lang as Locales });
-    };
-
-    return (
-        <div>
-            <button onClick={() => tonConnectUI.sendTransaction(myTransaction)}>
-                Send transaction
-            </button>
-
-            <div>
-                <label>language</label>
-                <select onChange={e => onLanguageChange(e.target.value)}>
-                    <option value="en">en</option>
-                    <option value="ru">ru</option>
-                </select>
-            </div>
-        </div>
-    );
+  const [tonConnectUI, setOptions] = useTonConnectUI();
+
+  const onLanguageChange = (language: Locales) => {
+    setOptions({ language });
+  };
+
+  return (
+    <div>
+      <label>language</label>
+      <select onChange={(e) => onLanguageChange(e.target.value as Locales)}>
+        <option value="en">en</option>
+        <option value="ru">ru</option>
+      </select>
+    </div>
+  );
 };
 ```
 
@@ -176,13 +195,13 @@ You can use it to detect when connection restoring process if finished.
 import { useIsConnectionRestored } from '@tonconnect/ui-react';
 
 export const EntrypointPage = () => {
-    const connectionRestored = useIsConnectionRestored();
+  const connectionRestored = useIsConnectionRestored();
 
-    if (!connectionRestored) {
-        return <Loader>Please wait...</Loader>;
-    }
+  if (!connectionRestored) {
+    return <Loader>Please wait...</Loader>;
+  }
 
-    return <MainPage />;
+  return <MainPage />;
 };
 ```
 
@@ -197,27 +216,29 @@ Send TON coins (in nanotons) to a specific address:
 ```js
 import { useTonConnectUI } from '@tonconnect/ui-react';
 
-const transaction = {
-    messages: [
-        {
-            address: "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F", // destination address
-            amount: "20000000" //Toncoin in nanotons
-        }
-    ]
-
-}
+const transaction: SendTransactionRequest = {
+  validUntil: Date.now() + 5 * 60 * 1000, // 5 minutes
+  messages: [
+    {
+      address:
+        "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F", // destination address
+      amount: "20000000", // Toncoin in nanotons
+    },
+  ],
+};
 
 export const Settings = () => {
-    const [tonConnectUI, setOptions] = useTonConnectUI();
-
-    return (
-        <div>
-            <button onClick={() => tonConnectUI.sendTransaction(transaction)}>
-                Send transaction
-            </button>
-        </div>
-    );
+  const [tonConnectUI, setOptions] = useTonConnectUI();
+
+  return (
+    <div>
+      <button onClick={() => tonConnectUI.sendTransaction(transaction)}>
+        Send transaction
+      </button>
+    </div>
+  );
 };
+
 ```
 
 - Get more examples here: [Preparing Messages](/develop/dapps/ton-connect/message-builders)
@@ -232,91 +253,78 @@ The principle located in Payment Processing (using tonweb). [See more](/develop/
 Understand how to sign and verify messages: [Signing and Verification](/develop/dapps/ton-connect/sign)
 :::
 
-Use `tonConnectUI.setConnectRequestParameters` function to pass your connect request parameters.
-
-This function takes one parameter:
-
-Set state to 'loading' while you are waiting for the response from your backend. If user opens connect wallet modal at this moment, he will see a loader.
-```ts
-const [tonConnectUI] = useTonConnectUI();
-
-tonConnectUI.setConnectRequestParameters({
-    state: 'loading'
-});
-```
+To ensure that the user truly owns the declared address, you can use `ton_proof`.
 
-or
+Use the `tonConnectUI.setConnectRequestParameters` function to set up your connection request parameters. You can use it for:
+- Loading State: Show a loading state while waiting for a response from your backend.
+- Ready State with tonProof: Set the state to 'ready' and include the tonProof value.
+- If an error occurs, remove the loader and create the connect request without additional parameters.
 
-Set state to 'ready' and define `tonProof` value. Passed parameter will be applied to the connect request (QR and universal link).
 ```ts
 const [tonConnectUI] = useTonConnectUI();
 
-tonConnectUI.setConnectRequestParameters({
-    state: 'ready',
-    value: {
-        tonProof: '<your-proof-payload>'
-    }
-});
-```
+// Set loading state
+tonConnectUI.setConnectRequestParameters({ state: "loading" });
 
-or
+// Fetch tonProofPayload from backend
+const tonProofPayload: string | null =
+  await fetchTonProofPayloadFromBackend();
 
-Remove loader if it was enabled via `state: 'loading'` (e.g. you received an error instead of a response from your backend). Connect request will be created without any additional parameters.
-```ts
-const [tonConnectUI] = useTonConnectUI();
-
-tonConnectUI.setConnectRequestParameters(null);
+if (tonProofPayload) {
+  // Set ready state with tonProof
+  tonConnectUI.setConnectRequestParameters({
+    state: "ready",
+    value: { tonProof: tonProofPayload },
+  });
+} else {
+  // Remove loader
+  tonConnectUI.setConnectRequestParameters(null);
+}
 ```
 
+#### Handling ton_proof Result
 
-You can call `tonConnectUI.setConnectRequestParameters` multiple times if your tonProof payload has bounded lifetime (e.g. you can refresh connect request parameters every 10 minutes).
-
+You can find `ton_proof` result in the `wallet` object when the wallet is connected:
 
 ```ts
-const [tonConnectUI] = useTonConnectUI();
-
-// enable ui loader
-tonConnectUI.setConnectRequestParameters({ state: 'loading' });
-
-// fetch you tonProofPayload from the backend
-const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();
-
-if (!tonProofPayload) {
-    // remove loader, connect request will be without any additional parameters
-    tonConnectUI.setConnectRequestParameters(null);
-} else {
-    // add tonProof to the connect request
-    tonConnectUI.setConnectRequestParameters({
-        state: "ready",
-        value: { tonProof: tonProofPayload }
+useEffect(() => {
+    tonConnectUI.onStatusChange((wallet) => {
+      if (
+        wallet.connectItems?.tonProof &&
+        "proof" in wallet.connectItems.tonProof
+      ) {
+        checkProofInYourBackend(
+          wallet.connectItems.tonProof.proof,
+          wallet.account.address
+        );
+      }
     });
-}
-
+  }, []);
 ```
 
-
-You can find `ton_proof` result in the `wallet` object when wallet will be connected:
+#### Structure of ton_proof
 
 ```ts
-import {useTonConnectUI} from "@tonconnect/ui-react";
-
-const [tonConnectUI] = useTonConnectUI();
-
-useEffect(() =>
-    tonConnectUI.onStatusChange(wallet => {
-        if (wallet.connectItems?.tonProof && 'proof' in wallet.connectItems.tonProof) {
-            checkProofInYourBackend(wallet.connectItems.tonProof.proof, wallet.account);
-        }
-    }), []);
+type TonProofItemReplySuccess = {
+  name: "ton_proof";
+  proof: {
+    timestamp: string; // Unix epoch time (seconds)
+    domain: {
+      lengthBytes: number; // Domain length
+      value: string;  // Domain name
+    };
+    signature: string; // Base64-encoded signature
+    payload: string; // Payload from the request
+  }
+}
 ```
 
+You can find an example of authentication on this [page](/develop/dapps/ton-connect/sign#react-example)
 
 ### Wallet Disconnection
 
 Call to disconnect the wallet:
 ```js
-import { useTonConnectUI } from '@tonconnect/ui-react';
-
 const [tonConnectUI] = useTonConnectUI();
 
 await tonConnectUI.disconnect();

From a836a4706cc75a43ddb11a4fa4f536ef6c103f49 Mon Sep 17 00:00:00 2001
From: mlikhtar <m.likhtar@pixelplex.io>
Date: Wed, 21 Aug 2024 14:44:00 +0300
Subject: [PATCH 2/2] add more info tonconnect/react doc

---
 docs/develop/dapps/ton-connect/react.mdx | 40 +++++++++++++++++++-----
 1 file changed, 32 insertions(+), 8 deletions(-)

diff --git a/docs/develop/dapps/ton-connect/react.mdx b/docs/develop/dapps/ton-connect/react.mdx
index 43240ec729..f9f5731397 100644
--- a/docs/develop/dapps/ton-connect/react.mdx
+++ b/docs/develop/dapps/ton-connect/react.mdx
@@ -69,10 +69,11 @@ export const Header = () => {
 };
 ```
 
-You can connect to a specific wallet using the `openSingleWalletModal` method:
+#### Connect with a specific wallet
+To open a modal window for a specific wallet, use the `openSingleWalletModal()` method. This method takes the wallet's `app_name` as a parameter (refer to the [wallets-list.json]('https://github.com/ton-blockchain/wallets-list/blob/main/wallets-v2.json') file) and opens the corresponding wallet modal. It returns a promise that resolves once the modal window has successfully opened.
 
 ```tsx
-<button onClick={() => tonConnectUI.openSingleWalletModal('tonwallet)}>
+<button onClick={() => tonConnectUI.openSingleWalletModal('tonwallet')}>
   Connect Wallet
 </button>
 ```
@@ -127,15 +128,32 @@ export const Address = () => {
 };
 ```
 
-### useTonWallet
+### useTonConnectModal
+Use this hook to access the functions for opening and closing the modal window. The hook returns an object with the current modal state and methods to open and close the modal.
 
-Use it to get user's current ton wallet. If wallet is not connected hook will return null.
+```tsx
+import { useTonConnectModal } from '@tonconnect/ui-react';
 
-See all wallet's properties:
+export const ModalControl = () => {
+    const { state, open, close } = useTonConnectModal();
 
-[Wallet interface](https://ton-connect.github.io/sdk/interfaces/_tonconnect_sdk.Wallet.html)
+    return (
+      <div>
+          <div>Modal state: {state?.status}</div>
+          <button onClick={open}>Open modal</button>
+          <button onClick={close}>Close modal</button>
+      </div>
+    );
+};
+```
+
+### useTonWallet
+
+Use this hook to retrieve the user's current TON wallet.
+If the wallet is not connected, the hook will return `null`. The `wallet` object provides common data such as the user's address, provider, [TON proof](/develop/dapps/ton-connect/sign), and other attributes (see the [Wallet interface](https://ton-connect.github.io/sdk/interfaces/_tonconnect_sdk.Wallet.html)).
+
+Additionally, you can access more specific details about the connected wallet, such as its name, image, and other attributes (refer to the [WalletInfo interface](https://ton-connect.github.io/sdk/types/_tonconnect_sdk.WalletInfo.html)).
 
-[WalletInfo interface](https://ton-connect.github.io/sdk/types/_tonconnect_sdk.WalletInfo.html)
 
 ```tsx
 import { useTonWallet } from '@tonconnect/ui-react';
@@ -149,6 +167,12 @@ export const Wallet = () => {
         <span>Connected wallet address: {wallet.account.address}</span>
         <span>Device: {wallet.device.appName}</span>
         <span>Connected via: {wallet.provider}</span>
+        {wallet.connectItems?.tonProof?.proof && <span>Ton proof: {wallet.connectItems.tonProof.proof}</span>}
+
+        <div>Connected wallet info:</div>
+        <div>
+          {wallet.name} <img src={wallet.imageUrl} />
+        </div>
       </div>
     )
   );
@@ -299,7 +323,7 @@ useEffect(() => {
         );
       }
     });
-  }, []);
+  }, [tonConnectUI]);
 ```
 
 #### Structure of ton_proof