@tonconnect/ui 0.0.3 → 0.0.6

package/README.md

@@ -1,3 +1,168 @@
-# TON Connect SDK UI
+# TON Connect UI
 
-⚠️ API is work in progress right now.
+⚠️ **API is work in progress right now. Don't use this package in production.**
+
+TonConnect UI is a UI kit for TonConnect SDK. Use it to connect your app to TON wallets via TonConnect protocol.
+
+If you use React for your dapp, take a look at [TonConnect UI React kit](https://github.com/ton-connect/sdk/tree/main/packages/ui-react).
+
+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).
+
+---
+
+[Latest API documentation](https://ton-connect.github.io/sdk/modules/_tonconnect_ui.html)
+
+# Getting started
+
+## Installation with npm
+`npm i @tonconnect/ui`
+
+# Usage
+
+## Create TonConnectUI instance
+```ts
+import TonConnectUI from '@tonconnect/ui'
+
+const tonConnectUI = new TonConnectUI({
+    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
+    buttonRootId: '<YOUR_CONNECT_BUTTON_ANCHOR_ID>'
+});
+```
+
+See all available options:
+[TonConnectUiOptionsWithManifest](https://ton-connect.github.io/sdk/docs/interfaces/_tonconnect_ui.TonConnectUiOptionsWithManifest.html)
+[TonConnectUiOptionsWithConnector](https://ton-connect.github.io/sdk/docs/interfaces/_tonconnect_ui.TonConnectUiOptionsWithConnector.html)
+
+## Change options if needed 
+```ts
+tonConnectUI.uiOptions = {
+    language: 'ru',
+    theme: THEME.DARK
+};
+```
+
+UI element will be rerendered after assignation. You should pass only options that you want to change.
+Passed options will be merged with current UI options. Note, that you have to pass object to `tonConnectUI.uiOptions` to keep reactivity.
+
+DON'T do this:
+```ts
+tonConnectUI.uiOptions.language = 'ru'; // WRONG, WILL NOT WORK 
+```
+
+[See all available options](https://ton-connect.github.io/sdk/docs/interfaces/_tonconnect_ui.TonConnectUiOptions.html)
+
+## Fetch wallets list
+```ts
+const walletsList = await tonConnectUI.getWallets();
+
+/* walletsList is 
+{
+    name: string;
+    imageUrl: string;
+    tondns?: string;
+    aboutUrl: string;
+    universalLink?: string;
+    deepLink?: string;
+    bridgeUrl?: string;
+    jsBridgeKey?: string;
+    injected?: boolean; // true if this wallet is injected to the webpage
+    embedded?: boolean; // true if the dapp is opened inside this wallet's browser
+}[] 
+ */
+```
+
+or
+
+```ts
+const walletsList = await TonConnectUI.getWallets();
+```
+
+## Call connect
+"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();
+```
+
+If there is an error while wallet connecting, `TonConnectUIError` or `TonConnectError` will be thrown depends on situation.
+
+## 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.
+
+```ts
+    const currentWallet = tonConnectUI.wallet;
+    const currentWalletInfo = tonConnectUI.walletInfo;
+    const currentAccount = tonConnectUI.account;
+    const currentIsConnectedStatus = tonConnectUI.connected;
+```
+
+## Subscribe to the connection status changes
+```js
+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.
+```
+
+## Disconnect wallet
+Call to disconnect the wallet.
+
+```ts
+await tonConnectUI.disconnect();
+```
+
+## Send transaction
+Wallet must be connected when you call `sendTransaction`. Otherwise, an error will be thrown.
+
+
+```ts
+const transaction = {
+    validUntil: Date.now() + 1000000,
+    messages: [
+        {
+            address: "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F",
+            amount: "20000000",
+            stateInit: "base64bocblahblahblah==" // just for instance. Replace with your transaction initState or remove
+        },
+        {
+            address: "0:E69F10CC84877ABF539F83F879291E5CA169451BA7BCE91A37A5CED3AB8080D3",
+            amount: "60000000",
+            payload: "base64bocblahblahblah==" // just for instance. Replace with your transaction payload or remove
+        }
+    ]
+}
+
+try {
+    const result = await tonConnectUI.sendTransaction(transaction);
+
+    // you can use signed boc to find the transaction 
+    const someTxData = await myAppExplorerService.getTransaction(result.boc);
+    alert('Transaction was sent successfully', someTxData);
+} catch (e) {
+    console.error(e);
+}
+```
+
+`sendTransaction` will automatically render informational modals and notifications. You can change its behaviour:
+
+```ts
+const result = await tonConnectUI.sendTransaction(defaultTx, {
+    modals: ['before', 'success', 'error'],
+    notifications: ['before', 'success', 'error']
+});
+```
+
+Default configuration is: 
+```ts
+const defaultBehaviour = {
+    modals: ['before'],
+    notifications: ['before', 'success', 'error']
+}
+```

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { WalletConnectionSource, ITonConnect, Account, Wallet, WalletInfo, SendTransactionRequest, SendTransactionResponse, TonConnectError } from '@tonconnect/sdk';
+import { WalletConnectionSource, ITonConnect, WalletInfo, Account, Wallet, TonConnectError, SendTransactionRequest, SendTransactionResponse } from '@tonconnect/sdk';
 import { Property } from 'csstype';
 
 declare enum THEME {
@@ -47,47 +47,89 @@ declare type Locales = 'en' | 'ru';
 declare type Color = Property.Color;
 
 interface TonConnectUiOptions {
+    /**
+     * Color theme for the UI elements.
+     * @default SYSTEM theme.
+     */
     theme?: Theme;
+    /**
+     * Accent color for the UI elements.
+     * @default #31A6F5 (blue).
+     */
     accentColor?: Color;
+    /**
+     * HTML element id to attach the wallet connect button. If not passed button won't appear.
+     * @default null.
+     */
     buttonRootId?: string | null;
+    /**
+     * Language for the phrases it the UI elements.
+     * @default system
+     */
     language?: Locales;
+    /**
+     * Configuration for the wallet connect button.
+     */
     buttonConfiguration?: Partial<ButtonConfiguration>;
+    /**
+     * Configuration for the wallet connect modal and action modals.
+     */
     widgetConfiguration?: Partial<WidgetConfiguration>;
 }
 
 declare type TonConnectUiCreateOptions = TonConnectUiOptionsWithConnector | TonConnectUiOptionsWithManifest;
 interface TonConnectUiOptionsWithManifest extends TonConnectUiCreateOptionsBase {
+    /**
+     * 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;
 }
 interface TonConnectUiOptionsWithConnector extends TonConnectUiCreateOptionsBase {
+    /**
+     * 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;
 }
 interface TonConnectUiCreateOptionsBase extends TonConnectUiOptions {
+    /**
+     * Try to restore existing session and reconnect to the corresponding wallet.
+     * @default true.
+     */
     restoreConnection?: boolean;
+    /**
+     * 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 class TonConnectUi {
+declare class TonConnectUI {
+    static getWallets(): Promise<WalletInfo[]>;
     private readonly walletInfoStorage;
     private readonly connector;
     private _walletInfo;
     private systemThemeChangeUnsubscribe;
     /**
-     * Current connection status
+     * Current connection status.
      */
     get connected(): boolean;
     /**
-     * Current connected account or null
+     * Current connected account or null.
      */
     get account(): Account | null;
     /**
-     * Curren connected wallet app or null
+     * Curren connected wallet app or null.
      */
     get wallet(): Wallet | null;
     /**
-     * Curren connected wallet's info or null
+     * Curren connected wallet's info or null.
      */
     get walletInfo(): WalletInfo | null;
+    /**
+     * Set and apply new UI options. Object with partial options should be passed. Passed options will be merged with current options.
+     * @param options
+     */
     set uiOptions(options: TonConnectUiOptions);
     constructor(options?: TonConnectUiCreateOptions);
     /**
@@ -95,27 +137,26 @@ declare class TonConnectUi {
      */
     getWallets(): Promise<WalletInfo[]>;
     /**
-     * Subscribe to connection status change
-     * @return function which has to be called to unsubscribe
+     * Subscribe to connection status change.
+     * @return function which has to be called to unsubscribe.
      */
-    onStatusChange(...parameters: Parameters<ITonConnect['onStatusChange']>): ReturnType<ITonConnect['onStatusChange']>;
+    onStatusChange(callback: (wallet: (Wallet & WalletInfo) | null) => void, errorsHandler?: (err: TonConnectError) => void): ReturnType<ITonConnect['onStatusChange']>;
     /**
      * Opens the modal window and handles a wallet connection.
      */
-    connectWallet(): Promise<Wallet>;
+    connectWallet(): Promise<Wallet & WalletInfo>;
     /**
      * Disconnect wallet and clean localstorage.
      */
     disconnect(): Promise<void>;
     /**
-     * Opens the modal window and handles the tx sending
-     * @param tx
-     * @param options
+     * Opens the modal window and handles the transaction sending.
+     * @param tx transaction to send.
+     * @param options modal and notifications behaviour settings. Default is show only 'before' modal and all notifications.
      */
     sendTransaction(tx: SendTransactionRequest, options?: {
-        showModalBefore: boolean;
-        showSuccessModalAfter: boolean;
-        showErrorModalAfter: boolean;
+        modals?: ('before' | 'success' | 'error')[];
+        notifications?: ('before' | 'success' | 'error')[];
     }): Promise<SendTransactionResponse>;
     private subscribeToWalletChange;
     private updateWalletInfo;
@@ -127,4 +168,4 @@ declare class TonConnectUIError extends TonConnectError {
     constructor(...args: ConstructorParameters<typeof Error>);
 }
 
-export { ButtonAppearance, ButtonConfiguration, ButtonSize, Locales, THEME, Theme, Themed, TonConnectUIError, TonConnectUi, TonConnectUiCreateOptions, TonConnectUiCreateOptionsBase, TonConnectUiOptions, TonConnectUiOptionsWithConnector, TonConnectUiOptionsWithManifest, WalletsListConfiguration, WalletsListConfigurationExplicit, WalletsListConfigurationImplicit, WidgetConfiguration, TonConnectUi as default };
+export { ButtonAppearance, ButtonConfiguration, ButtonSize, Locales, THEME, Theme, Themed, TonConnectUI, TonConnectUIError, TonConnectUiCreateOptions, TonConnectUiCreateOptionsBase, TonConnectUiOptions, TonConnectUiOptionsWithConnector, TonConnectUiOptionsWithManifest, WalletsListConfiguration, WalletsListConfigurationExplicit, WalletsListConfigurationImplicit, WidgetConfiguration, TonConnectUI as default };