@tonconnect/ui - npm Package Compare versions

Comparing version 0.0.8 to 0.0.9

lib/index.d.ts

 import { WalletInfoBase, WalletInfoInjected, WalletInfoRemote, ITonConnect, WalletInfo, Account, Wallet, TonConnectError, SendTransactionRequest, SendTransactionResponse } from '@tonconnect/sdk';
 import { Property } from 'csstype';
 
+declare type Locales = 'en' | 'ru';
+
 declare enum THEME {
@@ -10,16 +12,75 @@ DARK = "DARK",
 
+declare type BorderRadius = 'm' | 's' | 'none';
+
 declare type Color$1 = Property.Color;
+declare type ColorsSet = {
+    constant: {
+        black: Color$1;
+        white: Color$1;
+    };
+    connectButton: {
+        background: Color$1;
+        foreground: Color$1;
+    };
+    accent: Color$1;
+    icon: {
+        primary: Color$1;
+        secondary: Color$1;
+        tertiary: Color$1;
+        success: Color$1;
+    };
+    background: {
+        primary: Color$1;
+        secondary: Color$1;
+    };
+    text: {
+        primary: Color$1;
+        subhead: Color$1;
+        secondary: Color$1;
+    };
+};
+declare type PartialColorsSet = {
+    constant?: {
+        black?: Color$1;
+        white?: Color$1;
+    };
+    connectButton?: {
+        background?: Color$1;
+        foreground?: Color$1;
+    };
+    accent?: Color$1;
+    icon?: {
+        primary?: Color$1;
+        secondary?: Color$1;
+        tertiary?: Color$1;
+        success?: Color$1;
+    };
+    background?: {
+        primary?: Color$1;
+        secondary?: Color$1;
+    };
+    text?: {
+        primary?: Color$1;
+        subhead?: Color$1;
+        secondary?: Color$1;
+    };
+};
 
-interface Themed {
-    theme: Theme;
-    accentColor: Color$1;
+interface UIPreferences {
+    /**
+     * Color theme for the UI elements.
+     * @default SYSTEM theme.
+     */
+    theme?: Theme;
+    /**
+     * Birder radius for UI elements.
+     * @default 'm'
+     */
+    borderRadius?: BorderRadius;
+    /**
+     * Configure colors scheme for different themes.
+     */
+    colorsSet?: Partial<Record<THEME, PartialColorsSet>>;
 }
 
-declare type ButtonSize = 'm' | 'l';
-declare type ButtonAppearance = 'primary' | 'secondary' | 'flat';
-interface ButtonConfiguration extends Partial<Themed> {
-    size: ButtonSize;
-    appearance: ButtonAppearance;
-}
-
 declare type UIWallet = WalletInfoBase & (Omit<WalletInfoInjected, 'injected' | 'embedded'> | WalletInfoRemote);
@@ -56,24 +117,21 @@
 
-declare type ModalSize = 'm' | 'l';
-interface WidgetConfiguration extends Partial<Themed> {
-    size?: ModalSize;
-    wallets?: WalletsListConfiguration;
+interface ActionConfiguration {
+    /**
+     * Configure action modals behavior.
+     * @default ['before']
+     */
+    modals?: ('before' | 'success' | 'error')[] | 'all';
+    /**
+     * Configure action notifications behavior.
+     * @default 'all'
+     */
+    notifications?: ('before' | 'success' | 'error')[] | 'all';
 }
 
-declare type Locales = 'en' | 'ru';
-
-declare type Color = Property.Color;
-
 interface TonConnectUiOptions {
     /**
-     * Color theme for the UI elements.
-     * @default SYSTEM theme.
+     * UI elements configuration.
      */
-    theme?: Theme;
+    uiPreferences?: UIPreferences;
     /**
-     * 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.
@@ -89,9 +147,9 @@ * @default null.
     /**
-     * Configuration for the wallet connect button.
+     * Configuration for the wallets list in the connect wallet modal.
      */
-    buttonConfiguration?: Partial<ButtonConfiguration>;
+    walletsList?: WalletsListConfiguration;
     /**
-     * Configuration for the wallet connect modal and action modals.
+     * Configuration for action-period (e.g. sendTransaction) UI elements: modals and notifications.
      */
-    widgetConfiguration?: WidgetConfiguration;
+    actionsConfiguration?: ActionConfiguration;
     /**
@@ -136,2 +194,3 @@ * @deprecated Don't use it
     private systemThemeChangeUnsubscribe;
+    private actionsConfiguration?;
     /**
@@ -181,6 +240,3 @@ * Current connection status.
      */
-    sendTransaction(tx: SendTransactionRequest, options?: {
-        modals?: ('before' | 'success' | 'error')[];
-        notifications?: ('before' | 'success' | 'error')[];
-    }): Promise<SendTransactionResponse>;
+    sendTransaction(tx: SendTransactionRequest, options?: ActionConfiguration): Promise<SendTransactionResponse>;
     private subscribeToWalletChange;
@@ -190,4 +246,7 @@ private updateWalletInfo;
     private checkButtonRootExist;
+    private getModalsAndNotificationsConfiguration;
 }
 
+declare type Color = Property.Color;
+
 declare class TonConnectUIError extends TonConnectError {
@@ -197,2 +256,2 @@ constructor(...args: ConstructorParameters<typeof Error>);
 
-export { ButtonAppearance, ButtonConfiguration, ButtonSize, Locales, THEME, Theme, Themed, TonConnectUI, TonConnectUIError, TonConnectUiCreateOptions, TonConnectUiCreateOptionsBase, TonConnectUiOptions, TonConnectUiOptionsWithConnector, TonConnectUiOptionsWithManifest, WalletsListConfiguration, WalletsListConfigurationExplicit, WalletsListConfigurationImplicit, WidgetConfiguration, TonConnectUI as default };
+export { ActionConfiguration, BorderRadius, Color, ColorsSet, Locales, PartialColorsSet, THEME, Theme, TonConnectUI, TonConnectUIError, TonConnectUiCreateOptions, TonConnectUiCreateOptionsBase, TonConnectUiOptions, TonConnectUiOptionsWithConnector, TonConnectUiOptionsWithManifest, UIPreferences, UIWallet, WalletsListConfiguration, WalletsListConfigurationExplicit, WalletsListConfigurationImplicit, TonConnectUI as default };

package.json

 {
   "name": "@tonconnect/ui",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "scripts": {
     "start": "vite --host",
     "dev": "vite",
-    "build": "vite build && rollup -c rollup.config.mjs",
+    "build": "vite build && rollup -c rollup.config.mjs && vite build -c vite.cdn-config.ts",
     "serve": "vite preview"
@@ -33,3 +33,3 @@ },
   "license": "Apache-2.0",
-  "files": ["lib"],
+  "files": ["lib", "dist"],
   "main": "./lib/index.umd.cjs",
@@ -67,3 +67,4 @@ "module": "./lib/index.js",
     "rollup-plugin-dts": "^5.0.0",
-    "rollup": "^3.8.0"
+    "rollup": "^3.8.0",
+    "solid-devtools": "^0.24.7"
   },
@@ -70,0 +71,0 @@ "typedoc": {

README.md

@@ -19,2 +19,24 @@ # TON Connect UI
 
+## Installation with cdn
+Add the script to your HTML file:
+```html
+<script src="https://unpkg.com/@tonconnect/ui@latest/dist/tonconnect-ui.min.js"></script>
+```
+
+ℹ️ If you don't want auto-update the library, pass concrete version instead of `latest`, e.g.
+```html
+<script src="https://unpkg.com/@tonconnect/ui@0.0.9/dist/tonconnect-ui.min.js"></script>
+```
+
+You can find `TonConnectUI` in global variable `TON_CONNECT_UI`, e.g.
+```html
+<script>
+    const tonConnectUI = new TON_CONNECT_UI.TonConnectUI({
+        manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
+        buttonRootId: '<YOUR_CONNECT_BUTTON_ANCHOR_ID>'
+    });
+</script>
+```
+
+
 ## Installation with npm
@@ -45,3 +67,5 @@ `npm i @tonconnect/ui`
     language: 'ru',
-    theme: THEME.DARK
+    uiPreferences: {
+        theme: THEME.DARK
+    }
 };
@@ -55,3 +79,3 @@ ```
 ```ts
-tonConnectUI.uiOptions.language = 'ru'; // WRONG, WILL NOT WORK 
+/* WRONG, WILL NOT WORK */ tonConnectUI.uiOptions.language = 'ru'; 
 ```
@@ -174,1 +198,243 @@
 ```
+
+## UI customisation
+TonConnect UI provides an interface that should be familiar and recognizable to the user when using various apps. 
+However, the app developer can make changes to this interface to keep it consistent with the app interface.
+
+### Customise UI using tonconnectUI.uiOptions
+All such updates are reactive -- change `tonconnectUI.uiOptions` and changes will be applied immediately.  
+
+[See all available options](https://ton-connect.github.io/sdk/interfaces/_tonconnect_ui.UIPreferences.html)
+
+#### Change border radius
+There are three border-radius modes: `'m'`, `'s'` and `'none'`. Default is `'m'`. You can change it via tonconnectUI.uiOptions, or set on tonConnectUI creating:
+
+```ts
+/* Pass to the constructor */
+const tonConnectUI = new TonConnectUI({
+    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
+    uiPreferences: {
+        borderRadius: 's'
+    }
+});
+
+
+/* Or update dynamically */
+tonConnectUI.uiOptions = {
+        uiPreferences: {
+            borderRadius: 's'
+        }
+    };
+```
+
+Note, that `uiOptions` is a setter which will merge new options with previous ones. So you doesn't need to merge it explicitly. Just pass changed options.
+```ts
+/* DON'T DO THIS. SEE DESCRIPTION ABOVE */
+tonConnectUI.uiOptions = {
+        ...previousUIOptions,
+        uiPreferences: {
+            borderRadius: 's'
+        }
+    };
+
+/* Just pass changed property */
+tonConnectUI.uiOptions = {
+    uiPreferences: {
+        borderRadius: 's'
+    }
+};
+```
+
+#### Change theme
+You can set fixed theme: `'THEME.LIGHT'` or `'THEME.DARK'`, or use system theme. Default theme is system.
+
+```ts
+import { THEME } from '@tonconnect/ui';
+
+tonConnectUI.uiOptions = {
+        uiPreferences: {
+            theme: THEME.DARK
+        }
+    };
+```
+
+You also can set `'SYSTEM'` theme:
+```ts
+tonConnectUI.uiOptions = {
+        uiPreferences: {
+            theme: 'SYSTEM'
+        }
+    };
+```
+
+You can set theme in the constructor if needed:
+```ts
+import { THEME } from '@tonconnect/ui';
+
+const tonConnectUI = new TonConnectUI({
+    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
+    uiPreferences: {
+        theme: THEME.DARK
+    }
+});
+```
+
+#### Change colors scheme
+You can redefine all colors scheme for each theme or change some colors. Just pass colors that you want to change.
+
+```ts
+tonConnectUI.uiOptions = {
+        uiPreferences: {
+            colorsSet: {
+                [THEME.DARK]: {
+                    connectButton: {
+                        background: '#29CC6A'
+                    }
+                }
+            }
+        }
+    };
+```
+
+You can change colors for both themes at the same time:
+
+```ts
+tonConnectUI.uiOptions = {
+        uiPreferences: {
+            colorsSet: {
+                [THEME.DARK]: {
+                    connectButton: {
+                        background: '#29CC6A'
+                    }
+                },
+                [THEME.LIGHT]: {
+                    text: {
+                        primary: '#FF0000'
+                    }
+                }
+            }
+        }
+    };
+
+```
+
+You can set colors scheme in the constructor if needed:
+```ts
+import { THEME } from '@tonconnect/ui';
+
+const tonConnectUI = new TonConnectUI({
+    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
+    uiPreferences: {
+        colorsSet: {
+            [THEME.DARK]: {
+                connectButton: {
+                    background: '#29CC6A'
+                }
+            }
+        }
+    }
+});
+```
+
+[See all available options](https://ton-connect.github.io/sdk/interfaces/_tonconnect_ui.PartialColorsSet.html)
+
+#### Combine options
+It is possible to change all required options at the same time:
+
+```ts
+tonConnectUI.uiOptions = {
+        uiPreferences: {
+            theme: THEME.DARK,
+            borderRadius: 's',
+            colorsSet: {
+                [THEME.DARK]: {
+                    connectButton: {
+                        background: '#29CC6A'
+                    }
+                },
+                [THEME.LIGHT]: {
+                    text: {
+                        primary: '#FF0000'
+                    }
+                }
+            }
+        }
+    };
+```
+
+
+### Direct css customisation
+It is not recommended to customise TonConnect UI elements via css as it may confuse the user when looking for known and familiar UI elements such as connect button/modals.
+However, it is possible if needed. You can add css styles to the specified selectors of the UI element. See list of selectors in the table below:
+
+| Element                              | Selector                         | Element description                                                                               |
+|--------------------------------------|----------------------------------|---------------------------------------------------------------------------------------------------|
+| Connect wallet modal container       | `#tc-wallets-modal-container`    | Container of the modal window that opens when you click on the "connect wallet" button.           |
+| Select wallet modal content          | `#tc-wallets-modal`              | Content of the modal window with wallet selection.                                                |
+| QR-code modal content                | `#tc-qr-modal`                   | Content of the modal window with QR-code.                                                         |
+| Action modal container               | `#tc-actions-modal-container`    | Container of the modal window that opens when you call `sendTransaction` or other action.         |
+| Confirm action modal content         | `#tc-confirm-modal`              | Content of the modal window asking for confirmation of the action in the wallet.                  |
+| "Transaction sent" modal content     | `#tc-transaction-sent-modal`     | Content of the modal window informing that the transaction was successfully sent.                 |
+| "Transaction canceled" modal content | `#tc-transaction-canceled-modal` | Content of the modal window informing that the transaction was not sent.                          |
+| "Connect Wallet" button              | `#tc-connect-button`             | "Connect Wallet" button element.                                                                  |
+| Wallet menu dropdown button          | `#tc-dropdown-button`            | Wallet menu button -- host of the dropdown wallet menu (copy address/disconnect).                 |
+| Wallet menu dropdown container       | `#tc-dropdown-container`         | Container of the dropdown that opens when you click on the "wallet menu" button with ton address. |
+| Wallet menu dropdown content         | `#tc-dropdown`                   | Content of the dropdown that opens when you click on the "wallet menu" button with ton address.   |
+| Notifications container              | `#tc-notifications`              | Container of the actions notifications.                                                           |
+
+
+## Customize the list of displayed wallets
+You can customize the list of displayed wallets: change order, exclude wallets or add custom wallets.
+
+
+### Redefine wallets list
+Pass an array of the wallet's names and custom wallets. Array items order will be applied to the wallets in modal window.  
+
+You can define custom wallet with `jsBridgeKey` (wallet = browser extension or there is a wallet dapp browser) or with `bridgeUrl` and `universalLink` pair (for http-connection compatible wallets), or pass all of these properties. 
+```ts
+import { UIWallet } from '@tonconnect/ui';
+
+const customWallet: UIWallet = {
+    name: '<CUSTOM_WALLET_NAME>',
+    imageUrl: '<CUSTOM_WALLET_IMAGE_URL>',
+    aboutUrl: '<CUSTOM_WALLET_ABOUT_URL>',
+    jsBridgeKey: '<CUSTOM_WALLET_JS_BRIDGE_KEY>',
+    bridgeUrl: '<CUSTOM_WALLET_HTTP_BRIDGE_URL>',
+    universalLink: '<CUSTOM_WALLET_UNIVERSAL_LINK>'
+};
+
+tonConnectUI.uiOptions = {
+        walletsList: {
+            wallets: ['tonkeeper', 'openmask', customWallet]
+        }
+    };
+```
+
+### Modify default wallets list
+Exclude some wallets with `excludeWallets` property.
+Include custom wallets with `includeWallets` property.
+Setup place where custom wallets will appear in the all wallets list with `includeWalletsOrder`. Default value id `'end''`. 
+
+
+```ts
+import { UIWallet } from '@tonconnect/ui';
+
+const customWallet: UIWallet = {
+    name: '<CUSTOM_WALLET_NAME>',
+    imageUrl: '<CUSTOM_WALLET_IMAGE_URL>',
+    aboutUrl: '<CUSTOM_WALLET_ABOUT_URL>',
+    jsBridgeKey: '<CUSTOM_WALLET_JS_BRIDGE_KEY>',
+    bridgeUrl: '<CUSTOM_WALLET_HTTP_BRIDGE_URL>',
+    universalLink: '<CUSTOM_WALLET_UNIVERSAL_LINK>'
+};
+
+ tonConnectUI.uiOptions = {
+        walletsList: {
+            excludeWallets: ['openmask'],
+            includeWallets: [customWallet],
+            includeWalletsOrder: 'start'
+        }
+    };
+```
+
+[See all available options](https://ton-connect.github.io/sdk/types/_tonconnect_ui.WalletsListConfiguration.html)

No alert changes

Improved metrics

Total package byte prevSize

3117645

increased by44.19%

Number of package files

10

increased by25%

Lines of code

23371

increased by7.28%

Number of lines in readme file

437

increased by155.56%

Worsened metrics

Dev dependency count

9

increased by12.5%

Number of medium supply chain risk alerts

6

increased by50%

No dependency changes