@tonconnect/ui-react 0.0.3 → 0.0.5

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,19 +5,50 @@ 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;
+    /**
+     * @deprecated Don't use it
+     */
+    walletsListSource: string;
 }
 declare const _default: import("react").NamedExoticComponent<TonConnectUIProviderProps>;
 export default _default;

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;