@stellar-expert/ui-framework 1.16.8 → 1.17.0

package/asset/asset-selector.js

@@ -1,72 +1,73 @@
-import React, {useCallback, useRef, useState} from 'react'
-import {Dropdown} from '../controls/dropdown'
-import {AssetLink} from './asset-link'
-import {useAssetList} from './asset-list-hooks'
-import './asset-selector.scss'
-
-/**
- * @param {AssetSelectorOnAssetChanged} onChange - On asset selected callback
- * @param {String} [value] - Selected asset
- * @param {String[]} [predefinedAssets] - Optional lists of predefined assets that should be shown at the top of the dropdown list
- * @param {Boolean} [restricted] - If set, the selector is limited to the predefined assets list only
- * @param {String} [title] - Dropdown selector title
- * @param {String} [expanded] - Expanded by default
- * @return {JSX.Element}
- * @constructor
- */
-export function AssetSelector({value, predefinedAssets, onChange, restricted, title, expanded}) {
-    const [search, setSearch] = useState('')
-    const searchRef = useRef()
-    const options = []
-
-    const focusSearch = useCallback(() => {
-        setTimeout(() => searchRef.current?.focus(), 200)
-    }, [])
-
-    if (predefinedAssets) {
-        for (const asset of predefinedAssets) {
-            options.push({
-                value: asset,
-                title: <AssetLink link={false} asset={asset}/>,
-                hidden: search && !asset.split('-')[0].toLowerCase().includes(search.toLowerCase())
-            })
-        }
-    }
-
-    let loadNextPage
-    if (!restricted) {
-        const {assets, loadPage, loading} = useAssetList({search: search?.trim() || undefined})
-        for (let {asset} of assets) {
-            if (!predefinedAssets || !predefinedAssets.includes(asset)) {
-                options.push({value: asset, title: <AssetLink link={false} asset={asset}/>})
-            }
-        }
-        if (!options.filter(opt => !opt.hidden).length) {
-            if (loading) {
-                options.push({value: '...', disabled: true, title: <div className="loader"/>})
-            } else {
-                options.push({
-                    value: 'no',
-                    disabled: true,
-                    title: <div className="dimmed text-center text-small">(not found)</div>
-                })
-            }
-        }
-        loadNextPage = loadPage
-    }
-
-    return <Dropdown solo className="asset-selector" options={options} value={value} onOpen={focusSearch} title={title} expanded={expanded}
-                     showToggle={!title} onChange={onChange} onScroll={e => e.rel === 'bottom' && loadNextPage?.call(this)} header={<>
-        <h3>Select an asset</h3>
-        <div className="relative">
-            <input type="text" value={search} ref={searchRef} onChange={e => setSearch(e.target.value)}
-                   placeholder="Search by asset code or website"/>
-            <i className="icon-search dimmed"/>
-        </div>
-    </>}/>
-}
-
-/**
- * @callback AssetSelectorOnAssetChanged
- * @param {String} value
+import React, {useCallback, useRef, useState} from 'react'
+import {Dropdown} from '../controls/dropdown'
+import {AssetLink} from './asset-link'
+import {useAssetList} from './asset-list-hooks'
+import './asset-selector.scss'
+
+/**
+ * Asset picker dropdown with search
+ * @param {AssetSelectorOnAssetChanged} onChange - On asset selected callback
+ * @param {string} [value] - Selected asset
+ * @param {string[]} [predefinedAssets] - Optional lists of predefined assets that should be shown at the top of the dropdown list
+ * @param {boolean} [restricted] - If set, the selector is limited to the predefined assets list only
+ * @param {string} [title] - Dropdown selector title
+ * @param {string} [expanded] - Expanded by default
+ * @return {JSX.Element}
+ * @constructor
+ */
+export function AssetSelector({value, predefinedAssets, onChange, restricted, title, expanded}) {
+    const [search, setSearch] = useState('')
+    const searchRef = useRef()
+    const options = []
+
+    const focusSearch = useCallback(() => {
+        setTimeout(() => searchRef.current?.focus(), 200)
+    }, [])
+
+    if (predefinedAssets) {
+        for (const asset of predefinedAssets) {
+            options.push({
+                value: asset,
+                title: <AssetLink link={false} asset={asset}/>,
+                hidden: search && !asset.split('-')[0].toLowerCase().includes(search.toLowerCase())
+            })
+        }
+    }
+
+    let loadNextPage
+    if (!restricted) {
+        const {assets, loadPage, loading} = useAssetList({search: search?.trim() || undefined})
+        for (let {asset} of assets) {
+            if (!predefinedAssets || !predefinedAssets.includes(asset)) {
+                options.push({value: asset, title: <AssetLink link={false} asset={asset}/>})
+            }
+        }
+        if (!options.filter(opt => !opt.hidden).length) {
+            if (loading) {
+                options.push({value: '...', disabled: true, title: <div className="loader"/>})
+            } else {
+                options.push({
+                    value: 'no',
+                    disabled: true,
+                    title: <div className="dimmed text-center text-small">(not found)</div>
+                })
+            }
+        }
+        loadNextPage = loadPage
+    }
+
+    return <Dropdown solo className="asset-selector" options={options} value={value} onOpen={focusSearch} title={title} expanded={expanded}
+                     showToggle={!title} onChange={onChange} onScroll={e => e.rel === 'bottom' && loadNextPage?.call(this)} header={<>
+        <h3>Select an asset</h3>
+        <div className="relative">
+            <input type="text" value={search} ref={searchRef} onChange={e => setSearch(e.target.value)}
+                   placeholder="Search by asset code or website"/>
+            <i className="icon-search dimmed"/>
+        </div>
+    </>}/>
+}
+
+/**
+ * @callback AssetSelectorOnAssetChanged
+ * @param {string} value
  */

package/claimable-balance/claimable-balance-claimants.js

@@ -1,19 +1,24 @@
-import React from 'react'
-import {xdrParseClaimant} from '@stellar-expert/claimable-balance-utils'
-import {AccountAddress} from '../account/account-address'
-import {CodeBlock} from '../controls/code-block'
-
-export const ClaimableBalanceClaimants = React.memo(function ClaimableBalanceClaimants({claimants}) {
-    const parsed = claimants.map(c => {
-        if (c.destination && c.predicate && !c._predicate)
-            return c
-        return xdrParseClaimant(c)
-    })
-    return <>
-        {parsed.map((c, i) => <span key={i + c.destination}>{i > 0 && ', '}
-            <AccountAddress account={c.destination}/> {typeof c.predicate === 'string' ?
-                c.predicate :
-                <div className="block-indent"><CodeBlock>{JSON.stringify(c.predicate, null, 2)}</CodeBlock></div>}
-        </span>)}
-    </>
+import React from 'react'
+import {xdrParseClaimant} from '@stellar-expert/claimable-balance-utils'
+import {AccountAddress} from '../account/account-address'
+import {CodeBlock} from '../controls/code-block'
+
+/**
+ * Displays a list of claimable balance claimants with their addresses and predicates
+ * @param {Object} props
+ * @param {Array<Object>} props.claimants - Array of claimant objects (raw XDR or parsed)
+ */
+export const ClaimableBalanceClaimants = React.memo(function ClaimableBalanceClaimants({claimants}) {
+    const parsed = claimants.map(c => {
+        if (c.destination && c.predicate && !c._predicate)
+            return c
+        return xdrParseClaimant(c)
+    })
+    return <>
+        {parsed.map((c, i) => <span key={i + c.destination}>{i > 0 && ', '}
+            <AccountAddress account={c.destination}/> {typeof c.predicate === 'string' ?
+                c.predicate :
+                <div className="block-indent"><CodeBlock>{JSON.stringify(c.predicate, null, 2)}</CodeBlock></div>}
+        </span>)}
+    </>
 })

package/contract/contract-api.js

@@ -2,6 +2,11 @@ import {useEffect, useState} from 'react'
 import {useExplorerApi} from '../api/explorer-api-hooks'
 import {getCurrentStellarNetwork} from '../state/stellar-network-hooks'
 
+/**
+ * React hook that fetches contract information from the Explorer API
+ * @param {string} address - Contract address
+ * @return {ExplorerApiResult}
+ */
 export function useContractInfo(address) {
     return useExplorerApi('contract/' + address, {
         processResult(data) {
@@ -14,10 +19,20 @@ export function useContractInfo(address) {
     })
 }
 
+/**
+ * Generate a URL to download the WASM source for a contract
+ * @param {string} hash - Contract WASM hash
+ * @return {string} Full URL to the contract WASM source
+ */
 export function generateContractSourceLink(hash) {
     return `${explorerApiOrigin}/explorer/${getCurrentStellarNetwork()}/contract/wasm/${hash}`
 }
 
+/**
+ * React hook that fetches contract WASM binary source by hash
+ * @param {string} hash - Contract WASM hash
+ * @return {ArrayBuffer|null|undefined} WASM binary (undefined while loading, null if not found)
+ */
 export function useContractSource(hash) {
     const [source, setSource] = useState()
     useEffect(() => {

package/contract/invocation-info-view.js

@@ -8,6 +8,14 @@ import {parseScValValue, primitiveTypes, ScVal, ScValStruct} from './sc-val'
 import {useContractSource} from './contract-api'
 import {sacInterface} from './sac-interface'
 
+/**
+ * Basic Soroban contract invocation info
+ * @param {string} [contract] - Contract address
+ * @param {string} func - Invoked function name
+ * @param {Array|string} args - Function arguments (ScVal array or XDR string)
+ * @param {string|xdr.ScVal} [result] - Invocation result
+ * @param {string} [sac] - Stellar Asset Contract identifier
+ */
 export default function InvocationInfoView({contract, func, args, result, sac}) {
     if (typeof args === 'string') {
         args = parseScValValue(args)
@@ -45,13 +53,13 @@ const ExtendedInvocationInfoView = React.memo(function ({contract, func, args, r
     const fd = meta.functions[func]
     if (!fd)
         return <div className="error"><i className="icon-warning-circle"/> Failed to parse contract code</div>
-    const shouldIndent = args.length > 2 || Object.values(fd.inputs).some(i => !primitiveTypes.has(i.type)) // multi-line display for large argument number or complex types
+    const shouldIndent = args.length > 2 || fd.inputs.some(i => !primitiveTypes.has(i.type)) // multi-line display for large argument number or complex types
     const contractInfo = sac ?
         <> from asset <AssetLink asset={sac}/></> :
         <span className="text-tiny dimmed">
             &emsp;SDK v{meta.sdkVersion.split('#')[0]}&emsp;RUST v{shortenString(meta.rustVersion, 12)}
         </span>
-    const contractArgNames = Object.keys(fd.inputs)
+    const contractArgNames = fd.inputs.map(i => i.name)
     //TODO: show contract validation info
     return <div>
         <div>

package/contract/sc-val.js

@@ -1,108 +1,132 @@
-import React from 'react'
-import cn from 'classnames'
-import {xdr, scValToBigInt} from '@stellar/stellar-base'
-import {xdrParserUtils} from '@stellar-expert/tx-meta-effects-parser'
-import {shortenString} from '@stellar-expert/formatter'
-import {AccountAddress} from '../account/account-address'
-import './sc-val.scss'
-
-export const ScVal = React.memo(function ScVal({value, nested = false, indent = false, wrapObjects = true}) {
-    if (!nested)
-        return <code className={cn('sc-val', {block: indent})}><ScVal value={value} indent={indent} nested/></code>
-    if (!value)
-        return 'void'
-    if (typeof value === 'string') {
-        value = xdr.ScVal.fromXDR(value, 'base64')
-    }
-    if (value instanceof Array) {
-        const values = value.map((v, i) => <ScValStruct key={i} indent={indent} separate={value.length - i}>
-            <ScVal value={v} indent={indent} nested/>
-        </ScValStruct>)
-        return wrapObjects ? <>[{values}]</> : <>{values}</>
-    }
-    const val = value._value
-    switch (value._arm) {
-        case 'vec':
-            return <>[{val.map((v, i) => <ScValStruct key={i} indent={indent} separate={val.length - i}>
-                <ScVal value={v} indent={indent} nested/>
-            </ScValStruct>)}]</>
-        case 'map':
-            const values = val.map((kv, i) =>
-                <ScValStruct key={i} indent={indent} separate={val.length - i}>
-                    <ScVal value={kv.key()} indent={indent} nested/>: <ScVal value={kv.val()} indent={indent} nested/>
-                </ScValStruct>)
-            return wrapObjects ? <>&#123;{values}&#125;</> : <>{values}</>
-        case 'b':
-            return <>{val.toString()}<ScValType type="bool"/></>
-        case 'i32':
-        case 'u32':
-            return <>{val}<ScValType type={value._arm}/></>
-        case 'i256':
-        case 'u256':
-        case 'i128':
-        case 'u128':
-        case 'i64':
-        case 'u64':
-        case 'timepoint':
-        case 'duration':
-            return <>{scValToBigInt(value).toString()}<ScValType type={value._arm}/></>
-        case 'address':
-            switch (val._arm) {
-                case 'accountId':
-                    return <AccountAddress account={xdrParserUtils.xdrParseAccountAddress(val.value())}/>
-                case 'contractId':
-                    return <AccountAddress account={xdrParserUtils.xdrParseContractAddress(val.value())}/>
-                case 'muxedAccount':
-                    return <AccountAddress account={xdrParserUtils.xdrParseMuxedScAddress(val.value())}/>
-            }
-            return <span className="dimmed">(unsupported address)</span>
-        case 'bytes':
-            const asBytes = val.toString('base64')
-            return <><span className="condensed">{shortenString(asBytes, 86)}</span><ScValType type="bytes"/></>
-        case 'str':
-        case 'sym':
-            return <span className="word-break">"{val.toString()}"<ScValType type={value._arm}/></span>
-        case 'nonceKey':
-            return <>{val.nonce()._value.toString()}<ScValType type="nonce"/></>
-        case 'instance':
-            if (val._attributes.executable._switch.name==="contractExecutableStellarAsset")
-                return <span>StellarAsset<ScValType type="instance"/></span>
-            return <span className="word-break">{val._attributes.executable.wasmHash().toString('hex')}<ScValType type="wasm"/></span>
-        case 'error':
-            const errMessage = value.toXDR('base64')
-            return <><span className="condensed" title={errMessage}>{shortenString(errMessage, 50)}</span><ScValType type="error"/></>
-        case 'contractId':
-            return <AccountAddress account={xdrParserUtils.xdrParseContractAddress(value._value)}/>
-        default:
-            switch (value._switch.name) {
-                case 'scvVoid':
-                    return '()'
-                case 'scvContractInstance':
-                    return '<ContractInstance>'
-                case 'scvLedgerKeyContractInstance':
-                    return '<LedgerKeyContractInstance>'
-                case 'scvLedgerKeyNonce':
-                    return '<LedgerKeyNonce>'
-            }
-            return <span className="dimmed">(unknown)</span>
-    }
-})
-
-export function parseScValValue(value) {
-    return xdr.ScVal.fromXDR(value, 'base64')
-}
-
-const ScValType = React.memo(function ScValType({type}) {
-    return <sub className="dimmed text-tiny" style={{padding: '0 0.2em'}}>{type}</sub>
-})
-
-export const ScValStruct = React.memo(function ScValStruct({indent, children, separate}) {
-    const separator = separate > 1 ? <>, </> : null
-    if (!indent)
-        return <>{children}{separator}</>
-    return <div className="block-indent">
-        {children}{separator}
-    </div>
-})
-
+import React from 'react'
+import cn from 'classnames'
+import {xdr, scValToBigInt} from '@stellar/stellar-base'
+import {xdrParserUtils} from '@stellar-expert/tx-meta-effects-parser'
+import {shortenString} from '@stellar-expert/formatter'
+import {AccountAddress} from '../account/account-address'
+import './sc-val.scss'
+
+/**
+ * Renders a Stellar smart contract value (ScVal) in a human-readable format
+ * @param {Object} props
+ * @param {string|xdr.ScVal|Array} props.value - ScVal as base64 XDR string, parsed XDR object, or array
+ * @param {boolean} [props.nested=false] - Whether this is a nested rendering (internal use)
+ * @param {boolean} [props.indent=false] - Enable block-level indentation for nested structures
+ * @param {boolean} [props.wrapObjects=true] - Wrap maps and arrays with brackets
+ */
+export const ScVal = React.memo(function ScVal({value, nested = false, indent = false, wrapObjects = true}) {
+    if (!nested)
+        return <code className={cn('sc-val', {block: indent})}><ScVal value={value} indent={indent} nested/></code>
+    if (!value)
+        return 'void'
+    if (typeof value === 'string') {
+        value = xdr.ScVal.fromXDR(value, 'base64')
+    }
+    if (value instanceof Array) {
+        const values = value.map((v, i) => <ScValStruct key={i} indent={indent} separate={value.length - i}>
+            <ScVal value={v} indent={indent} nested/>
+        </ScValStruct>)
+        return wrapObjects ? <>[{values}]</> : <>{values}</>
+    }
+    const val = value._value
+    switch (value._arm) {
+        case 'vec':
+            return <>[{val.map((v, i) => <ScValStruct key={i} indent={indent} separate={val.length - i}>
+                <ScVal value={v} indent={indent} nested/>
+            </ScValStruct>)}]</>
+        case 'map':
+            const values = val.map((kv, i) =>
+                <ScValStruct key={i} indent={indent} separate={val.length - i}>
+                    <ScVal value={kv.key()} indent={indent} nested/>: <ScVal value={kv.val()} indent={indent} nested/>
+                </ScValStruct>)
+            return wrapObjects ? <>&#123;{values}&#125;</> : <>{values}</>
+        case 'b':
+            return <>{val.toString()}<ScValType type="bool"/></>
+        case 'i32':
+        case 'u32':
+            return <>{val}<ScValType type={value._arm}/></>
+        case 'i256':
+        case 'u256':
+        case 'i128':
+        case 'u128':
+        case 'i64':
+        case 'u64':
+        case 'timepoint':
+        case 'duration':
+            return <>{scValToBigInt(value).toString()}<ScValType type={value._arm}/></>
+        case 'address':
+            switch (val._arm) {
+                case 'accountId':
+                    return <AccountAddress account={xdrParserUtils.xdrParseAccountAddress(val.value())}/>
+                case 'contractId':
+                    return <AccountAddress account={xdrParserUtils.xdrParseContractAddress(val.value())}/>
+                case 'muxedAccount':
+                    return <AccountAddress account={xdrParserUtils.xdrParseMuxedScAddress(val.value())}/>
+            }
+            return <span className="dimmed">(unsupported address)</span>
+        case 'bytes':
+            const asBytes = val.toString('base64')
+            return <><span className="condensed">{shortenString(asBytes, 86)}</span><ScValType type="bytes"/></>
+        case 'str':
+        case 'sym':
+            return <span className="word-break">"{val.toString()}"<ScValType type={value._arm}/></span>
+        case 'nonceKey':
+            return <>{val.nonce()._value.toString()}<ScValType type="nonce"/></>
+        case 'instance':
+            if (val._attributes.executable._switch.name==="contractExecutableStellarAsset")
+                return <span>StellarAsset<ScValType type="instance"/></span>
+            return <span className="word-break">{val._attributes.executable.wasmHash().toString('hex')}<ScValType type="wasm"/></span>
+        case 'error':
+            const errMessage = value.toXDR('base64')
+            return <><span className="condensed" title={errMessage}>{shortenString(errMessage, 50)}</span><ScValType type="error"/></>
+        case 'contractId':
+            return <AccountAddress account={xdrParserUtils.xdrParseContractAddress(value._value)}/>
+        default:
+            switch (value._switch.name) {
+                case 'scvVoid':
+                    return '()'
+                case 'scvContractInstance':
+                    return '<ContractInstance>'
+                case 'scvLedgerKeyContractInstance':
+                    return '<LedgerKeyContractInstance>'
+                case 'scvLedgerKeyNonce':
+                    return '<LedgerKeyNonce>'
+            }
+            return <span className="dimmed">(unknown)</span>
+    }
+})
+
+/**
+ * Parse a base64-encoded XDR ScVal string into an xdr.ScVal object
+ * @param {string} value - Base64-encoded XDR string
+ * @return {xdr.ScVal}
+ */
+export function parseScValValue(value) {
+    return xdr.ScVal.fromXDR(value, 'base64')
+}
+
+const ScValType = React.memo(function ScValType({type}) {
+    return <sub className="dimmed text-tiny" style={{padding: '0 0.2em'}}>{type}</sub>
+})
+
+/**
+ * Structural wrapper for ScVal elements, handling indentation and separators
+ * @param {Object} props
+ * @param {boolean} [props.indent] - Enable block-level indentation
+ * @param {*} props.children - Nested content
+ * @param {number} [props.separate] - Show comma separator when > 1
+ */
+export const ScValStruct = React.memo(function ScValStruct({indent, children, separate}) {
+    const separator = separate > 1 ? <>, </> : null
+    if (!indent)
+        return <>{children}{separator}</>
+    return <div className="block-indent">
+        {children}{separator}
+    </div>
+})
+
+/**
+ * Set of primitive ScVal type identifiers
+ * @type {Set<string>}
+ */
 export const primitiveTypes = new Set(['b', 'i32', 'u32', 'i256', 'u256', 'i128', 'u128', 'i64', 'u64', 'timepoint', 'duration', 'address', 'bytes', 'str', 'sym', 'nonceKey', 'contractId', 'instance'])

package/controls/button-group.js

@@ -1,20 +1,26 @@
-import React from 'react'
-import PropTypes from 'prop-types'
-import './button-group.scss'
-
-export const ButtonGroup = React.memo(function ButtonGroup({inline, children, ...otherProps}) {
-    if (inline)
-        return <span className="button-group" {...otherProps}>{children}</span>
-    return <div className="button-group" {...otherProps}>{children}</div>
-})
-
-ButtonGroup.propTypes = {
-    /**
-     * Nested buttons
-     */
-    children: PropTypes.any.isRequired,
-    /**
-     * Whether to render the group as inline element (span)
-     */
-    inline: PropTypes.bool
+import React from 'react'
+import PropTypes from 'prop-types'
+import './button-group.scss'
+
+/**
+ * Groups multiple buttons together with consistent spacing
+ * @param {Object} props
+ * @param {boolean} [props.inline] - Render as inline element (`<span>`) instead of block (`<div>`)
+ * @param {*} props.children - Nested buttons
+ */
+export const ButtonGroup = React.memo(function ButtonGroup({inline, children, ...otherProps}) {
+    if (inline)
+        return <span className="button-group" {...otherProps}>{children}</span>
+    return <div className="button-group" {...otherProps}>{children}</div>
+})
+
+ButtonGroup.propTypes = {
+    /**
+     * Nested buttons
+     */
+    children: PropTypes.any.isRequired,
+    /**
+     * Whether to render the group as inline element (span)
+     */
+    inline: PropTypes.bool
 }