@tonconnect/ui-react 0.0.3 → 0.0.4

package/README.md

@@ -1,3 +1,146 @@
-# TON Connect SDK UI React
+# TON Connect UI React
 
-⚠️ **API is work in progress right now.**
+⚠️ **API is work in progress right now. Don't use this package in production.**
+
+TonConnect UI React is a React UI kit for TonConnect SDK. Use it to connect your app to TON wallets via TonConnect protocol in React apps.
+
+If you don't use React for your app, take a look at [TonConnect UI](https://github.com/ton-connect/sdk/tree/main/packages/ui).
+
+If you want to use TonConnect on the server side, you should use the [TonConnect SDK](https://github.com/ton-connect/sdk/tree/main/packages/sdk).
+
+You can find more details and the protocol specification in the [docs](https://github.com/ton-connect/docs).
+
+---
+
+# Getting started
+
+[Latest API documentation](https://ton-connect.github.io/sdk/modules/_tonconnect_ui-react.html)
+
+# Getting started
+
+## Installation with npm
+`npm i @tonconnect/ui-react`
+
+# Usage
+
+## Add TonConnectUIProvider
+Add TonConnectUIProvider to the root of the app. You can specify UI options using props.
+[See all available options](TODO)
+
+All TonConnect UI hooks calls and `<TonConnectButton />` component must be placed inside `<TonConnectUIProvider>`.
+
+```tsx
+import { TonConnectUIProvider } from '@tonconnect/ui-react';
+
+export function App() {
+    return (
+        <TonConnectUIProvider manifestUrl="https://<YOUR_APP_URL>/tonconnect-manifest.json">
+            { /* Your app */ }
+        </TonConnectUIProvider>
+    );
+}
+
+```
+
+## Add TonConnect Button
+TonConnect Button is universal UI component for initializing connection. After wallet is connected it transforms to a wallet menu.
+It is recommended to place it in the top right corner of your app.
+
+```tsx
+export const Header = () => {
+    return (
+        <header>
+            <span>My App with React UI</span>
+            <TonConnectButton />
+        </header>
+    );
+};
+
+```
+
+You can add `className` and `style` props to the button as well. Note that you cannot pass child to the TonConnectButton. 
+`<TonConnectButton  className="my-button-class" style={{ float: "right" }}/>`
+
+## Use TonConnect UI hooks
+
+### 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.
+
+```tsx
+import { useTonAddress } from '@tonconnect/ui-react';
+
+export const Address = () => {
+    const userFriendlyAddress = useTonAddress();
+    const rawAddress = useTonAddress(false);
+
+    return (
+        address && (
+            <div>
+                <span>User-friendly address: {userFriendlyAddress}</span>
+                <span>Raw address: {rawAddress}</span>
+            </div>
+        )
+    );
+};
+```
+
+### useTonWallet
+Use it to get user's current ton wallet. If wallet is not connected hook will return null.
+
+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>
+        )
+    );
+};
+```
+
+### useTonConnectUI
+Use it to get access to the `TonConnectUI` instance and UI options updating function.
+
+[See more about TonConnectUI instance methods](https://github.com/ton-connect/sdk/tree/main/packages/ui#send-transaction)
+
+[See more about setOptions function](https://github.com/ton-connect/sdk/tree/main/packages/ui#change-options-if-needed)
+
+
+```tsx
+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>
+    );
+};
+```

package/lib/components/TonConnectUIProvider.d.ts

@@ -5,18 +5,45 @@ declare type Color = CSS.Property.Color;
 export declare const TonConnectUIContext: import("react").Context<TonConnectUI | null>;
 export declare type TonConnectUIProviderProps = {
     children: JSX.Element;
-} & Partial<TonConnectUIProviderPropsBase> & (TonConnectUIProviderPropsWithManifest | TonConnectUIProviderPropsWithConnector);
+} & Partial<TonConnectUIProviderPropsBase> & Partial<TonConnectUIProviderPropsWithManifest | TonConnectUIProviderPropsWithConnector>;
 export interface TonConnectUIProviderPropsWithManifest {
+    /**
+     * Url to the [manifest]{@link https://github.com/ton-connect/docs/blob/main/requests-responses.md#app-manifest} with the Dapp metadata that will be displayed in the user's wallet.
+     * If not passed, manifest from `${window.location.origin}/tonconnect-manifest.json` will be taken.
+     */
     manifestUrl: string;
 }
 export interface TonConnectUIProviderPropsWithConnector {
+    /**
+     * TonConnect instance. Can be helpful if you use custom ITonConnect implementation, or use both of @tonconnect/sdk and @tonconnect/ui in your app.
+     */
     connector: ITonConnect;
 }
 export interface TonConnectUIProviderPropsBase {
+    /**
+     * Try to restore existing session and reconnect to the corresponding wallet.
+     * @default true.
+     */
     restoreConnection: boolean;
+    /**
+     * Color theme for the UI elements.
+     * @default SYSTEM theme.
+     */
     theme: Theme;
+    /**
+     * Accent color for the UI elements.
+     * @default #31A6F5 (blue).
+     */
     accentColor: Color;
+    /**
+     * Language for the phrases it the UI elements.
+     * @default system
+     */
     language: Locales;
+    /**
+     * HTML element id to attach the modal window element. If not passed, `div#tc-widget-root` in the end of the <body> will be added and used.
+     * @default `div#tc-widget-root`.
+     */
     widgetRootId: string;
 }
 declare const _default: import("react").NamedExoticComponent<TonConnectUIProviderProps>;

package/lib/errors/index.d.ts

@@ -1,2 +1,2 @@
 export { TonConnectProviderNotSetError } from './ton-connect-provider-not-set.error';
-export { TonConnectUiReactError } from './ton-connect-ui-react.error';
+export { TonConnectUIReactError } from './ton-connect-ui-react.error';

package/lib/errors/ton-connect-provider-not-set.error.d.ts

@@ -1,4 +1,8 @@
-import { TonConnectUiReactError } from './ton-connect-ui-react.error';
-export declare class TonConnectProviderNotSetError extends TonConnectUiReactError {
+import { TonConnectUIReactError } from './ton-connect-ui-react.error';
+/**
+ * Thrown when either <TonConnectProvider> not added to the top of the tags tree,
+ * either there is an attempt using TonConnect UI hook or <TonConnectButton> inside <TonConnectProvider>
+ */
+export declare class TonConnectProviderNotSetError extends TonConnectUIReactError {
     constructor(...args: ConstructorParameters<typeof Error>);
 }

package/lib/errors/ton-connect-ui-react.error.d.ts

@@ -1,4 +1,7 @@
 import { TonConnectUIError } from '@tonconnect/ui';
-export declare class TonConnectUiReactError extends TonConnectUIError {
+/**
+ * Base class for TonConnectUIReact errors. You can check if the error was triggered by the @tonconnect/ui-react using `err instanceof TonConnectUIReactError`.
+ */
+export declare class TonConnectUIReactError extends TonConnectUIError {
     constructor(...args: ConstructorParameters<typeof Error>);
 }

package/lib/hooks/useTonAddress.d.ts

@@ -1 +1,5 @@
+/**
+ * Use it to get user's current ton wallet address. If wallet is not connected hook will return empty string.
+ * @param [userFriendly=true] allows to choose format of the address.
+ */
 export declare function useTonAddress(userFriendly?: boolean): string;

package/lib/hooks/useTonConnectUI.d.ts

@@ -1,2 +1,5 @@
 import { TonConnectUI, TonConnectUiOptions } from '@tonconnect/ui';
+/**
+ * Use it to get access to the `TonConnectUI` instance and UI options updating function.
+ */
 export declare function useTonConnectUI(): [TonConnectUI, (options: TonConnectUiOptions) => void];

package/lib/hooks/useTonWallet.d.ts

@@ -1,2 +1,5 @@
 import { Wallet, WalletInfo } from '@tonconnect/sdk';
+/**
+ * Use it to get user's current ton wallet. If wallet is not connected hook will return null.
+ */
 export declare function useTonWallet(): (Wallet & WalletInfo) | null;

package/lib/index.js

@@ -7776,7 +7776,6 @@ const AccountButtonDropdown = (props) => {
   const connector = useContext(ConnectorContext);
   const [isCopiedShown, setIsCopiedShown] = createSignal(false);
   const onCopy = () => __async(void 0, null, function* () {
-    console.log(tonConnectUi.account.address);
     const userFriendlyAddress = toUserFriendlyAddress$1(tonConnectUi.account.address);
     yield copyToClipboard(userFriendlyAddress);
     setIsCopiedShown(true);
@@ -8826,7 +8825,7 @@ function P(l2, u2, e2) {
 const _tmpl$$3 = /* @__PURE__ */ template$1(`<div></div>`);
 const AccountButton = () => {
   const connector = useContext(ConnectorContext);
-  const tonConnectUI = useContext(TonConnectUiContext);
+  const tonConnectUI2 = useContext(TonConnectUiContext);
   const [isOpened, setIsOpened] = createSignal(false);
   const [address, setAddress] = createSignal("");
   let dropDownRef;
@@ -8875,7 +8874,7 @@ const AccountButton = () => {
     get children() {
       return createComponent(AccountButtonStyled, {
         appearance: "flat",
-        onClick: () => tonConnectUI.connectWallet(),
+        onClick: () => tonConnectUI2.connectWallet(),
         get children() {
           return [createComponent(TonIcon, {}), createComponent(Text, {
             translationKey: "button.connectWallet",
@@ -11048,8 +11047,8 @@ const WalletsModal = () => {
   } = useI18n()[1];
   createEffect(() => locale(appState.language));
   const connector = useContext(ConnectorContext);
-  const tonConnectUI = useContext(TonConnectUiContext);
-  const [walletsList] = createResource(() => tonConnectUI.getWallets());
+  const tonConnectUI2 = useContext(TonConnectUiContext);
+  const [walletsList] = createResource(() => tonConnectUI2.getWallets());
   const [selectedWalletInfo, setSelectedWalletInfo] = createSignal(null);
   const onClose = () => {
     setWalletsModalOpen(false);
@@ -11335,8 +11334,8 @@ const widgetController = {
   setAction: (action2) => void setTimeout(() => setAction(action2)),
   clearAction: () => void setTimeout(() => setAction(null)),
   getSelectedWalletInfo: () => lastSelectedWalletInfo(),
-  renderApp: (root, tonConnectUI) => render(() => createComponent(App, {
-    tonConnectUI
+  renderApp: (root, tonConnectUI2) => render(() => createComponent(App, {
+    tonConnectUI: tonConnectUI2
   }), document.getElementById(root))
 };
 class TonConnectUIError extends TonConnectError$1 {
@@ -11650,6 +11649,8 @@ class TonConnectUI {
           console.error(e2);
           throw new TonConnectUIError("Unhandled error:" + e2);
         }
+      } finally {
+        widgetController.clearAction();
       }
     });
   }
@@ -11690,23 +11691,26 @@ class TonConnectUI {
   }
 }
 const TonConnectUIContext = createContext$1(null);
+let tonConnectUI = null;
 const TonConnectUIProvider = (_a) => {
   var _b = _a, {
     children: children2
   } = _b, options = __objRest(_b, [
     "children"
   ]);
-  const tonConnectUI = new TonConnectUI(options);
+  if (!tonConnectUI) {
+    tonConnectUI = new TonConnectUI(options);
+  }
   return /* @__PURE__ */ jsx(TonConnectUIContext.Provider, { value: tonConnectUI, children: children2 });
 };
 const TonConnectUIProvider$1 = memo$1(TonConnectUIProvider);
-class TonConnectUiReactError extends TonConnectUIError {
+class TonConnectUIReactError extends TonConnectUIError {
   constructor(...args) {
     super(...args);
-    Object.setPrototypeOf(this, TonConnectUiReactError.prototype);
+    Object.setPrototypeOf(this, TonConnectUIReactError.prototype);
   }
 }
-class TonConnectProviderNotSetError extends TonConnectUiReactError {
+class TonConnectProviderNotSetError extends TonConnectUIReactError {
   constructor(...args) {
     super(...args);
     Object.setPrototypeOf(this, TonConnectProviderNotSetError.prototype);
@@ -11721,10 +11725,10 @@ function checkProvider(provider) {
   return true;
 }
 function useTonConnectUI() {
-  const tonConnectUI = useContext$1(TonConnectUIContext);
-  checkProvider(tonConnectUI);
-  const setOptions = (options) => void (tonConnectUI.uiOptions = options);
-  return [tonConnectUI, setOptions];
+  const tonConnectUI2 = useContext$1(TonConnectUIContext);
+  checkProvider(tonConnectUI2);
+  const setOptions = (options) => void (tonConnectUI2.uiOptions = options);
+  return [tonConnectUI2, setOptions];
 }
 const buttonRootId = "ton-connect-button";
 const TonConnectButton = ({ className: className2, style: style2 }) => {
@@ -11736,15 +11740,15 @@ const TonConnectButton = ({ className: className2, style: style2 }) => {
 };
 const TonConnectButton$1 = memo$1(TonConnectButton);
 function useTonWallet() {
-  const [tonConnectUI] = useTonConnectUI();
+  const [tonConnectUI2] = useTonConnectUI();
   const [wallet, setWallet] = useState(
-    () => tonConnectUI.wallet && __spreadValues2(__spreadValues2({}, tonConnectUI.wallet), tonConnectUI.walletInfo)
+    () => tonConnectUI2.wallet && __spreadValues2(__spreadValues2({}, tonConnectUI2.wallet), tonConnectUI2.walletInfo)
   );
   useEffect(
-    () => tonConnectUI.onStatusChange((value) => {
+    () => tonConnectUI2.onStatusChange((value) => {
       setWallet(value);
     }),
-    [tonConnectUI]
+    [tonConnectUI2]
   );
   return wallet;
 }
@@ -14613,7 +14617,7 @@ export {
   TonConnectUI,
   TonConnectUIError,
   TonConnectUIProvider$1 as TonConnectUIProvider,
-  TonConnectUiReactError,
+  TonConnectUIReactError,
   useTonAddress,
   useTonConnectUI,
   useTonWallet