@tonconnect/ui 0.0.16 → 1.0.0-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +86 -67
- package/dist/tonconnect-ui.min.js +486 -253
- package/dist/tonconnect-ui.min.js.map +1 -1
- package/lib/index.d.ts +37 -47
- package/lib/index.js +5624 -4319
- package/lib/index.js.map +1 -1
- package/lib/index.umd.js +5000 -3695
- package/lib/index.umd.js.map +1 -1
- package/package.json +3 -4
package/README.md
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
# TON Connect UI
|
|
2
2
|
|
|
3
|
-
⚠️ **API is work in progress right now. Don't use this package in production.**
|
|
4
|
-
|
|
5
3
|
TonConnect UI is a UI kit for TonConnect SDK. Use it to connect your app to TON wallets via TonConnect protocol.
|
|
6
4
|
|
|
7
5
|
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).
|
|
@@ -423,29 +421,54 @@ tonConnectUI.uiOptions = {
|
|
|
423
421
|
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.
|
|
424
422
|
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:
|
|
425
423
|
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
|
429
|
-
|
|
430
|
-
|
|
|
431
|
-
|
|
|
432
|
-
|
|
|
433
|
-
|
|
|
434
|
-
|
|
|
435
|
-
|
|
|
436
|
-
|
|
|
437
|
-
|
|
|
438
|
-
|
|
|
439
|
-
|
|
|
440
|
-
|
|
|
424
|
+
UI components:
|
|
425
|
+
|
|
426
|
+
| Element | Selector | Element description |
|
|
427
|
+
|---------------------------------------|-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
|
|
428
|
+
| Connect wallet modal container | `[data-tc-wallets-modal-container="true"]` | Container of the modal window that opens when you click on the "connect wallet" button. |
|
|
429
|
+
| Select wallet mobile modal content | `[data-tc-wallets-modal-mobile="true"]` | Content of the mobile modal window with wallet selection. |
|
|
430
|
+
| Select wallet desktop modal content | `[data-tc-wallets-modal-desktop="true"]` | Content of the desktop window with wallet selection. |
|
|
431
|
+
| Desktop Universal QR content | `[data-tc-universal-qr-desktop="true"]` | Universal QR page content under the tab bar in the desktop wallets selection modal window. |
|
|
432
|
+
| Desktop wallets list content | `[data-tc-select-wallet-desktop="true"]` | Wallets list page content under the tab bar in the desktop wallets selection modal window. |
|
|
433
|
+
| Concrete wallet QR-code modal content | `[data-tc-wallet-qr-modal-desktop="true"]` | Content of the modal window with the concrete wallet QR-code. |
|
|
434
|
+
| Action modal container | `[data-tc-actions-modal-container="true"]` | Container of the modal window that opens when you call `sendTransaction` or other action. |
|
|
435
|
+
| Confirm action modal content | `[data-tc-confirm-modal="true"]` | Content of the modal window asking for confirmation of the action in the wallet. |
|
|
436
|
+
| "Transaction sent" modal content | `[data-tc-transaction-sent-modal="true"]` | Content of the modal window informing that the transaction was successfully sent. |
|
|
437
|
+
| "Transaction canceled" modal content | `[data-tc-transaction-canceled-modal="true"]` | Content of the modal window informing that the transaction was not sent. |
|
|
438
|
+
| "Connect Wallet" button | `[data-tc-connect-button="true"]` | "Connect Wallet" button element. |
|
|
439
|
+
| Wallet menu loading button | `[data-tc-connect-button-loading="true"]` | Button element which appears instead of "Connect Wallet" and dropdown menu buttons while restoring connection process |
|
|
440
|
+
| Wallet menu dropdown button | `[data-tc-dropdown-button="true"]` | Wallet menu button -- host of the dropdown wallet menu (copy address/disconnect). |
|
|
441
|
+
| Wallet menu dropdown container | `[data-tc-dropdown-container="true"]` | Container of the dropdown that opens when you click on the "wallet menu" button with ton address. |
|
|
442
|
+
| Wallet menu dropdown content | `[data-tc-dropdown="true"]` | Content of the dropdown that opens when you click on the "wallet menu" button with ton address. |
|
|
443
|
+
| Notifications container | `[data-tc-list-notifications="true"]` | Container of the actions notifications. |
|
|
444
|
+
| Notification confirm | `[data-tc-notification-confirm="true"]` | Confirmation notification element. |
|
|
445
|
+
| Notification tx sent | `[data-tc-notification-tx-sent="true"]` | Transaction sent notification element. |
|
|
446
|
+
| Notification cancelled tx | `[data-tc-notification-tx-cancelled="true"]` | Cancelled transaction notification element. |
|
|
447
|
+
|
|
448
|
+
---
|
|
449
|
+
|
|
450
|
+
Basic UI elements:
|
|
451
|
+
|
|
452
|
+
| Element | Selector |
|
|
453
|
+
|--------------------------------|---------------------------------|
|
|
454
|
+
| Button | `[data-tc-button="true"]` |
|
|
455
|
+
| Icon-button | `[data-tc-icon-button="true"]` |
|
|
456
|
+
| Modal window | `[data-tc-modal="true"]` |
|
|
457
|
+
| Notification | `[data-tc-notification="true"]` |
|
|
458
|
+
| Tab bar | `[data-tc-tab-bar="true"]` |
|
|
459
|
+
| H1 | `[data-tc-h1="true"]` |
|
|
460
|
+
| H2 | `[data-tc-h2="true"]` |
|
|
461
|
+
| H3 | `[data-tc-h3="true"]` |
|
|
462
|
+
| Text | `[data-tc-text="true"]` |
|
|
463
|
+
| Wallet-item | `[data-tc-wallet-item="true"]` |
|
|
441
464
|
|
|
442
465
|
|
|
443
466
|
## Customize the list of displayed wallets
|
|
444
467
|
You can customize the list of displayed wallets: change order, exclude wallets or add custom wallets.
|
|
445
468
|
|
|
446
469
|
|
|
447
|
-
###
|
|
448
|
-
Pass
|
|
470
|
+
### Extend wallets list
|
|
471
|
+
Pass custom wallets array to extend the wallets list. Passed wallets will be added to the end of the original wallets list.
|
|
449
472
|
|
|
450
473
|
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.
|
|
451
474
|
```ts
|
|
@@ -461,72 +484,68 @@ const customWallet: UIWallet = {
|
|
|
461
484
|
};
|
|
462
485
|
|
|
463
486
|
tonConnectUI.uiOptions = {
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
487
|
+
walletsListConfiguration: {
|
|
488
|
+
includeWallets: [customWallet]
|
|
489
|
+
}
|
|
490
|
+
}
|
|
468
491
|
```
|
|
469
492
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
Include custom wallets with `includeWallets` property.
|
|
473
|
-
Setup place where custom wallets will appear in the all wallets list with `includeWalletsOrder`. Default value id `'end''`.
|
|
493
|
+
## Add connect request parameters (ton_proof)
|
|
494
|
+
Use `tonConnectUI.setConnectRequestParameters` function to pass your connect request parameters.
|
|
474
495
|
|
|
496
|
+
This function takes one parameter:
|
|
475
497
|
|
|
498
|
+
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.
|
|
476
499
|
```ts
|
|
477
|
-
|
|
500
|
+
tonConnectUI.setConnectRequestParameters({
|
|
501
|
+
state: 'loading'
|
|
502
|
+
});
|
|
503
|
+
```
|
|
478
504
|
|
|
479
|
-
|
|
480
|
-
name: '<CUSTOM_WALLET_NAME>',
|
|
481
|
-
imageUrl: '<CUSTOM_WALLET_IMAGE_URL>',
|
|
482
|
-
aboutUrl: '<CUSTOM_WALLET_ABOUT_URL>',
|
|
483
|
-
jsBridgeKey: '<CUSTOM_WALLET_JS_BRIDGE_KEY>',
|
|
484
|
-
bridgeUrl: '<CUSTOM_WALLET_HTTP_BRIDGE_URL>',
|
|
485
|
-
universalLink: '<CUSTOM_WALLET_UNIVERSAL_LINK>'
|
|
486
|
-
};
|
|
505
|
+
or
|
|
487
506
|
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
}
|
|
507
|
+
Set state to 'ready' and define `tonProof` value. Passed parameter will be applied to the connect request (QR and universal link).
|
|
508
|
+
```ts
|
|
509
|
+
tonConnectUI.setConnectRequestParameters({
|
|
510
|
+
state: 'ready',
|
|
511
|
+
value: {
|
|
512
|
+
tonProof: '<your-proof-payload>'
|
|
513
|
+
}
|
|
514
|
+
});
|
|
495
515
|
```
|
|
496
516
|
|
|
497
|
-
|
|
517
|
+
or
|
|
498
518
|
|
|
519
|
+
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.
|
|
520
|
+
```ts
|
|
521
|
+
tonConnectUI.setConnectRequestParameters(null);
|
|
522
|
+
```
|
|
499
523
|
|
|
500
|
-
## Add connect request parameters (ton_proof)
|
|
501
|
-
Pass `getConnectParameters` async function to the `TonConnectUI` constructor. This callback will be called after `connectWallet` method call or `Connect Button` click before wallets list render.
|
|
502
|
-
|
|
503
|
-
In other words, if `getConnectParameters` is passed, there will be a following steps:
|
|
504
|
-
1. User clicks to the 'Connect Wallet' button, or `connectWallet` method is called
|
|
505
|
-
2. Wallets modal opens
|
|
506
|
-
3. Loader renders in the center of the modal
|
|
507
|
-
4. TonConnectUI calls `getConnectParameters` and waits while it resolves
|
|
508
|
-
5. Wallets list renders in the center of the modal
|
|
509
524
|
|
|
510
|
-
|
|
525
|
+
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).
|
|
511
526
|
|
|
512
|
-
If you have to make a http-request to your backend it this case, it is better to do it after app initialization (if possible) and return (probably completed) promise from the `getConnectParameters` to reduce loading time for the user.
|
|
513
527
|
|
|
514
528
|
```ts
|
|
515
|
-
|
|
516
|
-
|
|
529
|
+
// enable ui loader
|
|
530
|
+
tonConnectUI.setConnectRequestParameters({ state: 'loading' });
|
|
531
|
+
|
|
532
|
+
// fetch you tonProofPayload from the backend
|
|
533
|
+
const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();
|
|
534
|
+
|
|
535
|
+
if (!tonProofPayload) {
|
|
536
|
+
// remove loader, connect request will be without any additional parameters
|
|
537
|
+
tonConnectUI.setConnectRequestParameters(null);
|
|
538
|
+
} else {
|
|
539
|
+
// add tonProof to the connect request
|
|
540
|
+
tonConnectUI.setConnectRequestParameters({
|
|
541
|
+
state: "ready",
|
|
542
|
+
value: { tonProof: tonProofPayload }
|
|
543
|
+
});
|
|
544
|
+
}
|
|
517
545
|
|
|
518
|
-
const tonConnectUI = new TonConnectUI({
|
|
519
|
-
manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
|
|
520
|
-
buttonRootId: '<YOUR_CONNECT_BUTTON_ANCHOR_ID>',
|
|
521
|
-
getConnectParameters: async () => {
|
|
522
|
-
const tonProof = await tonProofPayloadPromise; // will be executed every time when wallets modal is opened. It is recommended to make an http-request in advance
|
|
523
|
-
return {
|
|
524
|
-
tonProof
|
|
525
|
-
};
|
|
526
|
-
}
|
|
527
|
-
});
|
|
528
546
|
```
|
|
529
547
|
|
|
548
|
+
|
|
530
549
|
You can find `ton_proof` result in the `wallet` object when wallet will be connected:
|
|
531
550
|
```ts
|
|
532
551
|
tonConnectUI.onStatusChange(wallet => {
|