From 950c593710e57d5edea31fdb5d6a5fb93df94dbf Mon Sep 17 00:00:00 2001 From: aelf-lxy Date: Tue, 25 Jun 2024 16:03:11 +0800 Subject: [PATCH] doc: add doc for @aelf-web-login/utils --- packages/starter/src/Demo/demo.tsx | 2 +- packages/utils/README.md | 473 ++++++++++++++++++++++++++++- packages/utils/package.json | 6 +- 3 files changed, 476 insertions(+), 5 deletions(-) diff --git a/packages/starter/src/Demo/demo.tsx b/packages/starter/src/Demo/demo.tsx index 2be273e7..3c5e37cd 100644 --- a/packages/starter/src/Demo/demo.tsx +++ b/packages/starter/src/Demo/demo.tsx @@ -47,7 +47,7 @@ const baseConfig = { chainId: CHAIN_ID, keyboard: true, noCommonBaseModal: false, - design: SignInDesignEnum.SocialDesign, // "SocialDesign" | "CryptoDesign" | "Web2Design" + design: SignInDesignEnum.CryptoDesign, // "SocialDesign" | "CryptoDesign" | "Web2Design" titleForSocialDesign: 'Crypto wallet', iconSrcForSocialDesign: 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNTYiIGhlaWdodD0iNTYiIHZpZXdCb3g9IjAgMCA1NiA1NiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPGcgaWQ9IkVsZiBFeHBsb3JlciI+CjxyZWN0IHdpZHRoPSI1NiIgaGVpZ2h0PSI1NiIgZmlsbD0id2hpdGUiLz4KPHBhdGggaWQ9IlNoYXBlIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiIGNsaXAtcnVsZT0iZXZlbm9kZCIgZD0iTTMwLjAwMDMgMTEuODQyQzMzLjEwNjkgMTEuODQyIDM1LjYyNTIgOS4zMjM3MSAzNS42MjUyIDYuMjE3MTlDMzUuNjI1MiAzLjExMDY4IDMzLjEwNjkgMC41OTIzNDYgMzAuMDAwMyAwLjU5MjM0NkMyNi44OTM4IDAuNTkyMzQ2IDI0LjM3NTUgMy4xMTA2OCAyNC4zNzU1IDYuMjE3MTlDMjQuMzc1NSA5LjMyMzcxIDI2Ljg5MzggMTEuODQyIDMwLjAwMDMgMTEuODQyWk01NS40MDkzIDI4LjAzNzhDNTUuNDA5MyAzNC4zNTc5IDUwLjI4NTggMzkuNDgxNCA0My45NjU3IDM5LjQ4MTRDMzcuNjQ1NSAzOS40ODE0IDMyLjUyMiAzNC4zNTc5IDMyLjUyMiAyOC4wMzc4QzMyLjUyMiAyMS43MTc2IDM3LjY0NTUgMTYuNTk0MSA0My45NjU3IDE2LjU5NDFDNTAuMjg1OCAxNi41OTQxIDU1LjQwOTMgMjEuNzE3NiA1NS40MDkzIDI4LjAzNzhaTTM1LjYyNTIgNDkuODU4MkMzNS42MjUyIDUyLjk2NDggMzMuMTA2OSA1NS40ODMxIDMwLjAwMDMgNTUuNDgzMUMyNi44OTM4IDU1LjQ4MzEgMjQuMzc1NSA1Mi45NjQ4IDI0LjM3NTUgNDkuODU4MkMyNC4zNzU1IDQ2Ljc1MTcgMjYuODkzOCA0NC4yMzM0IDMwLjAwMDMgNDQuMjMzNEMzMy4xMDY5IDQ0LjIzMzQgMzUuNjI1MiA0Ni43NTE3IDM1LjYyNTIgNDkuODU4MlpNMS4xOTczMyAxMi4yM0MtMC40NTEzMzEgMTYuNTk0MSAxLjg3NjE5IDIxLjU0MDEgNi4yNDAzIDIzLjE4ODdDOS4xNDk3IDI0LjI1NTUgMTIuMjUzMSAyMy42NzM2IDE0LjQ4MzYgMjEuODMxQzE2LjUyMDIgMjAuMzc2MyAxOS4xMzg3IDE5Ljg5MTQgMjEuNjYwMSAyMC44NjEyQzIzLjMwODggMjEuNDQzMSAyNC41Njk1IDIyLjUwOTkgMjUuNDQyNCAyMy44Njc2TDI1LjUzOTMgMjQuMDYxNUMyNS45MjczIDI0LjY0MzQgMjYuNTA5MSAyNS4yMjUzIDI3LjI4NSAyNS40MTkzQzI5LjAzMDYgMjYuMDk4MSAzMS4wNjcyIDI1LjEyODMgMzEuNjQ5MSAyMy4zODI3QzMyLjMyOCAyMS42MzcgMzEuMzU4MiAxOS42MDA1IDI5LjYxMjUgMTkuMDE4NkMyOC44MzY3IDE4LjcyNzYgMjguMDYwOCAxOC43Mjc2IDI3LjI4NSAxOS4wMTg2QzI1LjczMzMgMTkuNTAzNSAyMy45ODc3IDE5LjUwMzUgMjIuMzM5IDE4LjkyMTZDMTkuOTE0NSAxOC4wNDg4IDE4LjI2NTggMTYuMTA5MiAxNy41ODcgMTMuODc4NkwxNy40OSAxMy42ODQ3QzE3LjQ5IDEzLjU4NzcgMTcuNDkgMTMuNDkwNyAxNy4zOTMgMTMuNDkwN1YxMy4yOTY4QzE2LjcxNDIgMTAuNTgxMyAxNC44NzE1IDguMjUzNzggMTIuMDU5MSA3LjI4Mzk4QzcuNjk1IDUuNTM4MzQgMi43NDkwMSA3Ljc2ODg4IDEuMTk3MzMgMTIuMjNaTTYuMjQwMyAzMi44ODY4QzEuODc2MTkgMzQuNTM1NCAtMC40NTEzMzEgMzkuNDgxNCAxLjE5NzMzIDQzLjg0NTVDMi44NDU5OSA0OC4zMDY2IDcuNjk1IDUwLjUzNzIgMTIuMDU5MSA0OC43OTE1QzE0Ljg3MTUgNDcuODIxNyAxNi43MTQyIDQ1LjQ5NDIgMTcuMzkzIDQyLjc3ODdWNDIuNTg0OEMxNy40OSA0Mi41ODQ4IDE3LjQ5IDQyLjQ4NzggMTcuNDkgNDIuMzkwOEwxNy41ODcgNDIuMTk2OUMxOC4yNjU4IDM5Ljk2NjMgMTkuOTE0NSAzOC4wMjY3IDIyLjMzOSAzNy4xNTM5QzIzLjk4NzcgMzYuNTcyIDI1LjczMzMgMzYuNTcyIDI3LjI4NSAzNy4wNTY5QzI4LjA2MDggMzcuMzQ3OSAyOC44MzY3IDM3LjM0NzkgMjkuNjEyNSAzNy4wNTY5QzMxLjM1ODIgMzYuNDc1IDMyLjMyOCAzNC40Mzg1IDMxLjY0OTEgMzIuNjkyOEMzMS4wNjcyIDMwLjk0NzIgMjkuMDMwNiAyOS45Nzc0IDI3LjI4NSAzMC42NTYyQzI2LjUwOTEgMzAuODUwMiAyNS45MjczIDMxLjQzMjEgMjUuNTM5MyAzMi4wMTRMMjUuNDQyNCAzMi4yMDc5QzI0LjU2OTUgMzMuNTY1NiAyMy4zMDg4IDM0LjYzMjQgMjEuNjYwMSAzNS4yMTQzQzE5LjEzODcgMzYuMTg0MSAxNi41MjAyIDM1LjY5OTIgMTQuNDgzNiAzNC4yNDQ1QzEyLjI1MzEgMzIuNDAxOSA5LjE0OTcgMzEuODIgNi4yNDAzIDMyLjg4NjhaIiBmaWxsPSIjMjY2Q0QzIi8+CjwvZz4KPC9zdmc+Cg==', diff --git a/packages/utils/README.md b/packages/utils/README.md index ba38a01c..ea52988d 100644 --- a/packages/utils/README.md +++ b/packages/utils/README.md @@ -1 +1,472 @@ -## +# Introduction + +**@aelf-web-login/utils**: common utility library for aelf applications. + +# Install + +```Dockerfile +yarn add @aelf-web-login/utils +``` + +# Usage + +## useCheckAllowanceAndApprove + +```ts +const useCheckAllowanceAndApprove: ({ + tokenContractAddress, + approveTargetAddress, + account, + amount, + symbol, + chainId, +}: { + tokenContractAddress: string; + approveTargetAddress: string; + account: string; + amount: string | number; + symbol: string; + chainId: TChainId; +}) => { + start: () => Promise; + loading: boolean; +}; +``` + +> compose getAllowance and approve code snippet + +```tsx +import { useConnectWallet } from '@aelf-web-login/wallet-adapter-react'; +import { useCheckAllowanceAndApprove } from '@aelf-web-login/utils'; +import { Button } from 'aelf-design'; + +const Demo = () => { + const { walletInfo, isConnected } = useConnectWallet(); + const { start, loading } = useCheckAllowanceAndApprove({ + tokenContractAddress: 'ASh2Wt7nSEmYqnGxPPzp4pnVDU4uhj1XW9Se5VeZcX2UDdyjx', + approveTargetAddress: 'ASh2Wt7nSEmYqnGxPPzp4pnVDU4uhj1XW9Se5VeZcX2UDdyjx', + account: walletInfo?.address as string, + amount: '10', + symbol: 'ELF', + chainId: 'tDVW', + }); + const checkAllowanceAndApproveHandler = async () => { + const rs = await start(); + console.log(rs); + }; + + return ( + + ); +}; +``` + +## useGetBalance + +```ts +const useGetBalance: ({ + tokenContractAddress, + account, + symbol, + chainId, +}: { + tokenContractAddress: string; + account: string; + symbol: string; + chainId: TChainId; +}) => { + getBalance: () => Promise; + loading: boolean; +}; +``` + +> hook for get balance + +```tsx +import { useConnectWallet } from '@aelf-web-login/wallet-adapter-react'; +import { useGetBalance } from '@aelf-web-login/utils'; +import { Button } from 'aelf-design'; + +const Demo = () => { + const { walletInfo, isConnected } = useConnectWallet(); + const { getBalance, loading } = useGetBalance({ + tokenContractAddress: 'ASh2Wt7nSEmYqnGxPPzp4pnVDU4uhj1XW9Se5VeZcX2UDdyjx', + account: walletInfo?.address as string, + symbol: 'ELF', + chainId: 'tDVW', + }); + const getBalanceHandler = async () => { + const rs = await getBalance(); + console.log(rs); + }; + + return ( + + ); +}; +``` + +## getRawTransaction + +```ts +interface IRawTransactionPrams { + walletInfo: TWalletInfo; + walletType: WalletTypeEnum; + params: any; + methodName: string; + contractAddress: string; + caContractAddress?: string; + rpcUrl: string; +} +const getRawTransaction: (params: IRawTransactionPrams) => Promise; +``` + +> compose getRawTransaction method of different wallet type + +```tsx +import { useConnectWallet } from '@aelf-web-login/wallet-adapter-react'; +import { getRawTransaction } from '@aelf-web-login/utils'; +import { Button } from 'aelf-design'; + +const Demo = () => { + const { walletInfo, walletType, isConnected } = useConnectWallet(); + const getRawTransactionHandler = async () => { + const rs = await getRawTransaction({ + walletInfo: walletInfo, + walletType: walletType, + params: { symbol: 'ELF', owner: walletInfo?.address }, + methodName: 'GetBalance', + contractAddress: 'ASh2Wt7nSEmYqnGxPPzp4pnVDU4uhj1XW9Se5VeZcX2UDdyjx', + caContractAddress: 'ASh2Wt7nSEmYqnGxPPzp4pnVDU4uhj1XW9Se5VeZcX2UDdyjx', + rpcUrl: 'https://tdvw-test-node.aelf.io', + }); + console.log(rs); + }; + + return ( + + ); +}; +``` + +## getTxResultRetry + +```ts +function getTxResultRetry(TransactionId: string, rpcUrl: string, reGetCount?: number): Promise; +``` + +> get transaction result use polling + +```tsx +import { getTxResultRetry } from '@aelf-web-login/utils'; +import { Button } from 'aelf-design'; +const Demo = () => { + const getTxResultRetryHandler = async () => { + const rs = await getTxResultRetry( + '7511408b1ad12f6c14c8cc7cbca1a458b170bc3821812733768a2acb3cd433dc', + 'https://tdvw-test-node.aelf.io', + ); + console.log(rs); + }; + + return ( + + ); +}; +``` + +## getOriginalAddress + +```ts +function getOriginalAddress(address: string): string; +``` + +> get original address, remove the head and tail of the address + +```tsx +import { getOriginalAddress } from '@aelf-web-login/utils'; +const Demo = () => { + return ( +
{getOriginalAddress('ELF_rRZCro3wsAk2mW1s4CvM66wCe8cYgKKBCUFGuBhF6rUtoQNyk_tDVW')}
+ ); +}; +``` + +## addPrefixSuffix + +```ts +function addPrefixSuffix(str: string, chainId?: string): string; +``` + +> add the head and tail of the address + +```tsx +import { addPrefixSuffix } from '@aelf-web-login/utils'; +const Demo = () => { + return
{addPrefixSuffix('rRZCro3wsAk2mW1s4CvM66wCe8cYgKKBCUFGuBhF6rUtoQNyk')}
; +}; +``` + +## decodeAddress + +```ts +const decodeAddress: (address: string) => boolean; +``` + +> decode a wallet address + +```tsx +import { decodeAddress } from '@aelf-web-login/utils'; +const Demo = () => { + return
{decodeAddress('rRZCro3wsAk2mW1s4CvM66wCe8cYgKKBCUFGuBhF6rUtoQNyk') + ''}
; +}; +``` + +## formatTime + +```ts +function formatTime(date: string | number, formats?: string): string; +``` + +> format time, follow dayjs + +```tsx +import { formatTime } from '@aelf-web-login/utils'; +const Demo = () => { + return
{formatTime('2021/9/11')}
; +}; +``` + +## createDuration + +```ts +function createDuration(units: DurationUnitsObjectType): Duration; +function createDuration(time: number, unit?: DurationUnitType): Duration; +function createDuration(ISO_8601: string): Duration; +``` + +> Create a duration object. + +```tsx +import { createDuration } from '@aelf-web-login/utils'; +const Demo = () => { + return ( +
{createDuration({ days: 3, hours: 3, minutes: 45 }).format('DD[d] HH[h] mm[m]')}
+ ); +}; +``` + +## formatNumberWithDecimalPlaces + +```ts +function formatNumberWithDecimalPlaces(val: BigNumber.Value, decimal?: number): string; +``` + +> format number with decimal places + +```tsx +import { formatNumberWithDecimalPlaces } from '@aelf-web-login/utils'; +const Demo = () => { + return
{formatNumberWithDecimalPlaces('12345.6789', 3)}
; +}; +``` + +## formatPrice + +```ts +function formatPrice( + price: number | BigNumber | string, + toFixedProps?: { + decimalPlaces?: number; + roundingMode?: BigNumber.RoundingMode; + minValue?: number; + }, +): string; +``` + +> format price, when the price is less than minValue, will show '< minValue' + +```tsx +import { formatPrice } from '@aelf-web-login/utils'; +const Demo = () => { + return
{formatPrice(1111.1234, { minValue: 1200 })}
; +}; +``` + +## isELFAddress + +```ts +function isELFAddress(value: string): boolean; +``` + +> Determine whether the parameters are valid elf address + +```tsx +import { isELFAddress } from '@aelf-web-login/utils'; +const Demo = () => { + return
{isELFAddress('rRZCro3wsAk2mW1s4CvM66wCe8cYgKKBCUFGuBhF6rUtoQNyk') + ''}
; +}; +``` + +## isPortkeyApp + +```ts +function isPortkeyApp(): boolean; +``` + +> Determine whether the current environment is in Portkey APP + +```tsx +import { isPortkeyApp } from '@aelf-web-login/utils'; +const Demo = () => { + return
{isPortkeyApp() + ''}
; +}; +``` + +## isPrivateKey + +```ts +function isPrivateKey(privateKey?: string): boolean; +``` + +> Determine whether the parameters are valid private key + +```tsx +import { isPrivateKey } from '@aelf-web-login/utils'; +const Demo = () => { + return ( +
+ {isPrivateKey( + '048001adae89cca64f63b8d014b16fd2519a61fa68bac9bc147684e589fbe8c4b976e7927fb3362d4ce14e8249d71390e16aeaf1eac3dc5e24a6c7ba3700d199b4', + ) + ''} +
+ ); +}; +``` + +## isMobileDevices + +```ts +function isMobileDevices(): boolean; +``` + +> Determine whether the current environment is mobile + +```tsx +import { isMobileDevices } from '@aelf-web-login/utils'; +const Demo = () => { + return
{isMobileDevices() + ''}
; +}; +``` + +## isAElfBridge + +```ts +function isAElfBridge(aelfBridge: AElfDappBridge): boolean; +``` + +> Receive a parameter of any, return whether it is AElfDappBridge's instance. + +```tsx +import { isAElfBridge } from '@aelf-web-login/utils'; +const Demo = () => { + return
{isAElfBridge({ x: 1 } as any) + ''}
; +}; +``` + +## divDecimals + +``` +function divDecimals(a: BigNumber.Value, decimals?: string | number): BigNumber +``` + +```tsx +import { divDecimals } from '@aelf-web-login/utils'; +const Demo = () => { + return
{divDecimals(100000000, 8).toString()}
; +}; +``` + +## timesDecimals + +``` +function timesDecimals(a: BigNumber.Value, decimals?: string | number): BigNumber +``` + +```tsx +import { timesDecimals } from '@aelf-web-login/utils'; +const Demo = () => { + return
{timesDecimals(1, 8).toString()}
; +}; +``` + +## Loading + +> Receive a parameter of React.ReactNode type, return a instance including a 'show' and 'hide' method. + +```tsx +import { Loading } from '@aelf-web-login/utils'; +import { Button, Loading as AelfdLoading } from 'aelf-design'; +import +const Demo = () => { + const loadingInstance = new Loading( + ( + + ), + ); + const onLoadingHandler = () => { + loadingInstance.show(); + setTimeout(() => { + loadingInstance.hide(); + }, 3000); + }; + return ( + + ) +} +``` + +## sleep + +``` +sleep: (milliseconds: number) => Promise +``` + +> Set a waiting time + +```tsx +import { sleep } from '@aelf-web-login/utils'; +import { Button } from 'aelf-design'; +const Demo = () => { + const [sleepMsg, setSleep] = useState(''); + return ( +
+ + {sleepMsg} +
+ ); +}; +``` diff --git a/packages/utils/package.json b/packages/utils/package.json index 5eafe678..59afc4e2 100755 --- a/packages/utils/package.json +++ b/packages/utils/package.json @@ -35,7 +35,9 @@ "@aelf-web-login/wallet-adapter-portkey-discover": "workspace:*", "@aelf-web-login/wallet-adapter-react": "workspace:*", "react": "^18.0.0", - "react-dom": "^18.0.0" + "react-dom": "^18.0.0", + "bignumber.js": "^9.1.2", + "dayjs": "^1.11.11" }, "devDependencies": { "@aelf-react/types": "^0.1.10", @@ -55,8 +57,6 @@ "@types/react-dom": "^18.3.0", "aelf-sdk": "^3.4.12", "babel-jest": "^29.7.0", - "bignumber.js": "^9.1.2", - "dayjs": "^1.11.11", "father": "^4.3.8", "identity-obj-proxy": "^3.0.0", "jest": "^29.7.0",