@mysten/dapp-kit 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @mysten/dapp-kit
 
+## 1.0.4
+
+### Patch Changes
+
+- 43e69f8: Add embedded LLM-friendly docs to published packages
+- Updated dependencies [43e69f8]
+- Updated dependencies [e51dc5d]
+  - @mysten/slush-wallet@1.0.3
+  - @mysten/sui@2.8.0
+  - @mysten/wallet-standard@0.20.1
+
 ## 1.0.3
 
 ### Patch Changes

package/docs/index.md

@@ -0,0 +1,91 @@
+# Sui dApp Kit (Legacy)
+
+> dApp Kit API reference for @mysten/dapp-kit
+
+> **Warning:** **Deprecated - JSON RPC Only**: This legacy version of `@mysten/dapp-kit` only works
+> with the deprecated JSON RPC API and will not be updated to support gRPC or GraphQL. For new
+> projects, use [`@mysten/dapp-kit-core` and `@mysten/dapp-kit-react`](/dapp-kit).
+
+The Sui dApp Kit is a set of React components, hooks, and utilities to help you build a dApp for the
+Sui ecosystem. Its hooks and components provide an interface for querying data from the Sui network
+and connecting to Sui wallets.
+
+### Core Features
+
+Some of the core features of the dApp Kit include:
+
+- Query hooks to get the information your dApp needs
+- Automatic wallet state management
+- Support for all Sui wallets
+- Pre-built React components
+- Lower level hooks for custom components
+
+## Install
+
+To use the Sui dApp Kit in your project, run the following command in your project root:
+
+```sh npm2yarn
+npm i --save @mysten/dapp-kit @mysten/sui @tanstack/react-query
+```
+
+## Setting up providers
+
+To use the hooks and components in the dApp Kit, wrap your app with the providers shown in the
+following example. The props available on the providers are covered in more detail in their
+respective pages.
+
+```tsx
+// Config options for the networks you want to connect to
+const { networkConfig } = createNetworkConfig({
+	localnet: { url: getFullnodeUrl('localnet') },
+	mainnet: { url: getFullnodeUrl('mainnet') },
+});
+const queryClient = new QueryClient();
+
+function App() {
+	return (
+		<QueryClientProvider client={queryClient}>
+			<SuiClientProvider networks={networkConfig} defaultNetwork="localnet">
+				<WalletProvider>
+					<YourApp />
+				</WalletProvider>
+			</SuiClientProvider>
+		</QueryClientProvider>
+	);
+}
+```
+
+## Using UI components to connect to a wallet
+
+The dApp Kit provides a set of flexible UI components that you can use to connect and manage wallet
+accounts from your dApp. The components are built on top of
+[Radix UI](https://www.radix-ui.com/primitives) and are customizable.
+
+To use the provided UI components, import the dApp Kit CSS stylesheet into your dApp. For more
+information regarding customization options, check out the respective documentation pages for the
+components and [themes](/dapp-kit/legacy/themes).
+
+```tsx
+
+```
+
+## Using hooks to make RPC calls
+
+The dApp Kit provides a set of hooks for making RPC calls to the Sui blockchain. The hooks are thin
+wrappers around `useQuery` from `@tanstack/react-query`. For more comprehensive documentation on how
+to use these query hooks, check out the
+[react-query documentation](https://tanstack.com/query/latest/docs/react/overview).
+
+```tsx
+function MyComponent() {
+	const { data, isPending, error, refetch } = useSuiClientQuery('getOwnedObjects', {
+		owner: '0x123',
+	});
+
+	if (isPending) {
+		return <div>Loading...</div>;
+	}
+
+	return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
+```

package/docs/llms-index.md

@@ -0,0 +1,27 @@
+# dApp Kit (Legacy)
+
+> Build Sui dapps in React with @mysten/dapp-kit
+
+- [Sui dApp Kit (Legacy)](./index.md): dApp Kit API reference for @mysten/dapp-kit
+- [SuiClientProvider](./sui-client-provider.md): React provider for Sui client configuration
+- [Rpc Hooks](./rpc-hooks.md): React hooks for Sui RPC queries
+- [WalletProvider](./wallet-provider.md): React provider for wallet connections
+- [ConnectButton](./wallet-components/ConnectButton.md): React connect button component
+- [ConnectModal](./wallet-components/ConnectModal.md): React connect modal component
+- [useAccounts](./wallet-hooks/useAccounts.md): List wallet accounts
+- [useAutoConnectWallet](./wallet-hooks/useAutoConnectWallet.md): Automatically reconnect to the
+  last connected wallet
+- [useConnectWallet](./wallet-hooks/useConnectWallet.md): Connect a wallet to the dApp
+- [useCurrentAccount](./wallet-hooks/useCurrentAccount.md): Get the current wallet account
+- [useCurrentWallet](./wallet-hooks/useCurrentWallet.md): Get the current wallet connection
+- [useDisconnectWallet](./wallet-hooks/useDisconnectWallet.md): Disconnect the current wallet
+- [useSignAndExecuteTransaction](./wallet-hooks/useSignAndExecuteTransaction.md): Sign and execute a
+  transaction
+- [useSignPersonalMessage](./wallet-hooks/useSignPersonalMessage.md): Sign a personal message with
+  the connected wallet
+- [useSignTransaction](./wallet-hooks/useSignTransaction.md): Sign a transaction without executing
+  it
+- [useSwitchAccount](./wallet-hooks/useSwitchAccount.md): Switch the active wallet account
+- [useWallets](./wallet-hooks/useWallets.md): List available wallet extensions
+- [Slush Integration](./slush.md): Slush wallet integration for dApp Kit
+- [Themes](./themes.md): theming API for dApp Kit components

package/docs/rpc-hooks.md

@@ -0,0 +1,161 @@
+# Rpc Hooks
+
+> React hooks for Sui RPC queries
+
+Sui dApp Kit ships with hooks for each of the RPC methods defined in the
+[JSON RPC specification](https://docs.sui.io/sui-api-ref).
+
+## useSuiClientQuery
+
+Load data from the Sui RPC using the `useSuiClientQuery` hook. This hook is a wrapper around the
+[useQuery](https://tanstack.com/query/latest/docs/react/guides/queries) hook from
+@tanstack/react-query.
+
+The hook takes the RPC method name as the first argument and any parameters as the second argument.
+You can pass any additional `useQuery` options as the third argument. You can read the
+[useQuery documentation](https://tanstack.com/query/latest/docs/react/guides/queries) for more
+details on the full set of options available.
+
+```tsx
+function MyComponent() {
+	const { data, isPending, isError, error, refetch } = useSuiClientQuery(
+		'getOwnedObjects',
+		{ owner: '0x123' },
+		{
+			gcTime: 10000,
+		},
+	);
+
+	if (isPending) {
+		return <div>Loading...</div>;
+	}
+
+	if (isError) {
+		return <div>Error: {error.message}</div>;
+	}
+
+	return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
+```
+
+## useSuiClientQueries
+
+You can fetch a variable number of Sui RPC queries using the `useSuiClientQueries` hook. This hook
+is a wrapper around the
+[useQueries](https://tanstack.com/query/latest/docs/react/reference/useQueries) hook from
+@tanstack/react-query.
+
+The `queries` value is an array of query option objects identical to the `useSuiClientQuery` hook.
+
+The `combine` parameter is optional. Use this parameter to combine the results of the queries into a
+single value. The result is structurally shared to be as referentially stable as possible.
+
+```tsx
+function MyComponent() {
+	const { data, isPending, isError } = useSuiClientQueries({
+		queries: [
+			{
+				method: 'getAllBalances',
+				params: {
+					owner: '0x123',
+				},
+			},
+			{
+				method: 'queryTransactionBlocks',
+				params: {
+					filter: {
+						FromAddress: '0x123',
+					},
+				},
+			},
+		],
+		combine: (result) => {
+			return {
+				data: result.map((res) => res.data),
+				isSuccess: result.every((res) => res.isSuccess),
+				isPending: result.some((res) => res.isPending),
+				isError: result.some((res) => res.isError),
+			};
+		},
+	});
+
+	if (isPending) {
+		return <div>Loading...</div>;
+	}
+
+	if (isError) {
+		return <div>Fetching Error</div>;
+	}
+
+	return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
+```
+
+## useSuiClientInfiniteQuery
+
+For RPC methods that support pagination, dApp Kit also implements a `useSuiClientInfiniteQuery`
+hook. For more details check out the
+[`useInfiniteQuery` documentation](https://tanstack.com/query/latest/docs/react/guides/infinite-queries).
+
+```tsx
+function MyComponent() {
+	const { data, isPending, isError, error, isFetching, fetchNextPage, hasNextPage } =
+		useSuiClientInfiniteQuery('getOwnedObjects', {
+			owner: '0x123',
+		});
+
+	if (isPending) {
+		return <div>Loading...</div>;
+	}
+
+	if (isError) {
+		return <div>Error: {error.message}</div>;
+	}
+
+	return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
+```
+
+## useSuiClientMutation
+
+For RPC methods that mutate state, dApp Kit implements a `useSuiClientMutation` hook. Use this hook
+with any RPC method to imperatively call the RPC method. For more details, check out the
+[`useMutation` documentation](https://tanstack.com/query/latest/docs/react/guides/mutations).
+
+```tsx
+function MyComponent() {
+	const { mutate } = useSuiClientMutation('dryRunTransactionBlock');
+
+	return (
+		<Button
+			onClick={() => {
+				mutate({
+					transactionBlock: tx,
+				});
+			}}
+		>
+			Dry run transaction
+		</Button>
+	);
+}
+```
+
+## useResolveSuiNSName
+
+To get the SuiNS name for a given address, use the `useResolveSuiNSName` hook.
+
+```tsx
+function MyComponent() {
+	const { data, isPending } = useResolveSuiNSName('0x123');
+
+	if (isPending) {
+		return <div>Loading...</div>;
+	}
+
+	if (data) {
+		return <div>Domain name is: {data}</div>;
+	}
+
+	return <div>Domain name not found</div>;
+}
+```

package/docs/slush.md

@@ -0,0 +1,29 @@
+# Slush Integration
+
+> Slush wallet integration for dApp Kit
+
+dApp Kit provides out-of-the-box opt-in support for the [Slush wallet](/slush-wallet/dapp).
+
+## Setup
+
+To enable support for Slush wallets, pass the `slushWallet` object to the `WalletProvider`
+component. This object has the following properties:
+
+- **`name`** - The name of your dApp, shown to the user when connecting to the dApp.
+
+```tsx
+function App({ children }) {
+	return (
+		<WalletProvider
+			slushWallet={{
+				name: 'Your dApp name',
+			}}
+		>
+			{children}
+		</WalletProvider>
+	);
+}
+```
+
+> Note: In the connect modal, users with the Slush Wallet extension installed will only see the
+> extension. If they don’t have it, the connection will default to the Slush web app.

package/docs/sui-client-provider.md

@@ -0,0 +1,191 @@
+# SuiClientProvider
+
+> React provider for Sui client configuration
+
+The `SuiClientProvider` manages the active `SuiJsonRpcClient` that hooks and components use in the
+dApp Kit.
+
+## Usage
+
+Place the `SuiClientProvider` at the root of your app and wrap all components that use the dApp Kit
+hooks.
+
+`SuiClientProvider` accepts a list of network configurations to create `SuiJsonRpcClient` instances
+for the currently active network.
+
+```tsx
+// Config options for the networks you want to connect to
+const { networkConfig } = createNetworkConfig({
+	localnet: { url: getJsonRpcFullnodeUrl('localnet') },
+	mainnet: { url: getJsonRpcFullnodeUrl('mainnet') },
+});
+
+function App() {
+	return (
+		<SuiClientProvider networks={networkConfig} defaultNetwork="localnet">
+			<YourApp />
+		</SuiClientProvider>
+	);
+}
+```
+
+## Props
+
+- `networks`: A map of networks you can use. The keys are the network names, and the values can be
+  either a configuration object (`SuiClientOptions`) or a `SuiJsonRpcClient` instance.
+- `defaultNetwork`: The name of the network to use by default when using the `SuiClientProvider` as
+  an uncontrolled component.
+- `network`: The name of the network to use when using the `SuiClientProvider` as a controlled
+  component.
+- `onNetworkChange`: A callback when the active network changes.
+- `createClient`: A callback when a new `SuiJsonRpcClient` is created (for example, when the active
+  network changes). It receives the network name and configuration object as arguments, returning a
+  `SuiJsonRpcClient` instance.
+
+## Controlled component
+
+The following example demonstrates a `SuiClientProvider` used as a controlled component.
+
+```tsx
+// Config options for the networks you want to connect to
+const { networkConfig } = createNetworkConfig({
+	localnet: { url: getJsonRpcFullnodeUrl('localnet') },
+	mainnet: { url: getJsonRpcFullnodeUrl('mainnet') },
+});
+
+function App() {
+	const [activeNetwork, setActiveNetwork] = useState('localnet' as keyof typeof networks);
+
+	return (
+		<SuiClientProvider
+			networks={networkConfig}
+			network={activeNetwork}
+			onNetworkChange={(network) => {
+				setActiveNetwork(network);
+			}}
+		>
+			<YourApp />
+		</SuiClientProvider>
+	);
+}
+```
+
+## SuiJsonRpcClient customization
+
+The following example demonstrates how to create a custom `SuiJsonRpcClient`.
+
+```tsx
+// Config options for the networks you want to connect to
+const networks = {
+	localnet: { url: getJsonRpcFullnodeUrl('localnet') },
+	mainnet: { url: getJsonRpcFullnodeUrl('mainnet') },
+} satisfies Record<string, SuiClientOptions>;
+
+function App() {
+	return (
+		<SuiClientProvider
+			networks={networks}
+			defaultNetwork="localnet"
+			createClient={(network, config) => {
+				return new SuiJsonRpcClient({
+					transport: new SuiHTTPTransport({
+						url: 'https://api.safecoin.org',
+						rpc: {
+							headers: {
+								Authorization: 'xyz',
+							},
+						},
+					}),
+				});
+			}}
+		>
+			<YourApp />
+		</SuiClientProvider>
+	);
+}
+```
+
+## Using the SuiJsonRpcClient from the provider
+
+To use the `SuiJsonRpcClient` from the provider, import the `useSuiClient` function from the
+`@mysten/dapp-kit` module.
+
+```tsx
+function MyComponent() {
+	const client = useSuiClient();
+
+	// use the client
+}
+```
+
+## Creating a network selector
+
+The dApp Kit doesn't provide its own network switcher, but you can use the `useSuiClientContext`
+hook to get the list of networks and set the active one:
+
+```tsx
+function NetworkSelector() {
+	const ctx = useSuiClientContext();
+
+	return (
+		<div>
+			{Object.keys(ctx.networks).map((network) => (
+				<button key={network} onClick={() => ctx.selectNetwork(network)}>
+					{`select ${network}`}
+				</button>
+			))}
+		</div>
+	);
+}
+```
+
+## Using network specific configuration
+
+If your dApp runs on multiple networks, the IDs for packages and other configurations might change,
+depending on which network you're using. You can use `createNetworkConfig` to create per-network
+configurations that your components can access.
+
+The `createNetworkConfig` function returns the provided configuration, along with hooks you can use
+to get the variables defined in your configuration.
+
+- `useNetworkConfig` returns the full network configuration object
+- `useNetworkVariables` returns the full variables object from the network configuration
+- `useNetworkVariable` returns a specific variable from the network configuration
+
+```tsx
+// Config options for the networks you want to connect to
+const { networkConfig, useNetworkVariable } = createNetworkConfig({
+	localnet: {
+		url: getJsonRpcFullnodeUrl('localnet'),
+		variables: {
+			myMovePackageId: '0x123',
+		},
+	},
+	mainnet: {
+		url: getJsonRpcFullnodeUrl('mainnet'),
+		variables: {
+			myMovePackageId: '0x456',
+		},
+	},
+});
+
+const queryClient = new QueryClient();
+
+function App() {
+	return (
+		<QueryClientProvider client={queryClient}>
+			<SuiClientProvider networks={networkConfig} defaultNetwork="localnet">
+				<WalletProvider>
+					<YourApp />
+				</WalletProvider>
+			</SuiClientProvider>
+		</QueryClientProvider>
+	);
+}
+
+function YourApp() {
+	const id = useNetworkVariable('myMovePackageId');
+
+	return <div>Package ID: {id}</div>;
+}
+```

package/docs/themes.md

@@ -0,0 +1,115 @@
+# Themes
+
+> theming API for dApp Kit components
+
+You can provide a theme to the `WalletProvider` component to customize the components in dApp Kit.
+
+```tsx
+const App = () => {
+	return (
+		<WalletProvider theme={lightTheme}>
+			<YourApp />
+		</WalletProvider>
+	);
+};
+```
+
+## Dynamic themes
+
+To dynamically change the theme, you can provide multiple themes to the `WalletProvider` component:
+
+```tsx
+const App = () => {
+	return (
+		<WalletProvider
+			theme={[
+				{
+					// default to light theme
+					variables: lightTheme,
+				},
+				{
+					// Adds theme inside a media query
+					mediaQuery: '(prefers-color-scheme: dark)',
+					variables: darkTheme,
+				},
+				{
+					// prefixes the theme styles with the given selector
+					// this allows controlling the theme by adding a class to the body
+					selector: '.pink-theme',
+					variables: pinkTheme,
+				},
+			]}
+		>
+			<YourApp />
+		</WalletProvider>
+	);
+};
+```
+
+## Theme variables
+
+To define a custom theme, implement the `ThemeVars` interface with CSS variable values for your
+theme:
+
+```tsx
+
+// Light theme copied from dapp-kit
+
+	blurs: {
+		modalOverlay: 'blur(0)',
+	},
+	backgroundColors: {
+		primaryButton: '#F6F7F9',
+		primaryButtonHover: '#F0F2F5',
+		outlineButtonHover: '#F4F4F5',
+		modalOverlay: 'rgba(24 36 53 / 20%)',
+		modalPrimary: 'white',
+		modalSecondary: '#F7F8F8',
+		iconButton: 'transparent',
+		iconButtonHover: '#F0F1F2',
+		dropdownMenu: '#FFFFFF',
+		dropdownMenuSeparator: '#F3F6F8',
+		walletItemSelected: 'white',
+		walletItemHover: '#3C424226',
+	},
+	borderColors: {
+		outlineButton: '#E4E4E7',
+	},
+	colors: {
+		primaryButton: '#373737',
+		outlineButton: '#373737',
+		iconButton: '#000000',
+		body: '#182435',
+		bodyMuted: '#767A81',
+		bodyDanger: '#FF794B',
+	},
+	radii: {
+		small: '6px',
+		medium: '8px',
+		large: '12px',
+		xlarge: '16px',
+	},
+	shadows: {
+		primaryButton: '0px 4px 12px rgba(0, 0, 0, 0.1)',
+		walletItemSelected: '0px 2px 6px rgba(0, 0, 0, 0.05)',
+	},
+	fontWeights: {
+		normal: '400',
+		medium: '500',
+		bold: '600',
+	},
+	fontSizes: {
+		small: '14px',
+		medium: '16px',
+		large: '18px',
+		xlarge: '20px',
+	},
+	typography: {
+		fontFamily:
+			'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+		fontStyle: 'normal',
+		lineHeight: '1.3',
+		letterSpacing: '1',
+	},
+};
+```

package/docs/wallet-components/ConnectButton.md

@@ -0,0 +1,22 @@
+# ConnectButton
+
+> React connect button component
+
+The `ConnectButton` shows the user a button to connect and disconnect a wallet. It automatically
+uses the connected state to show a **connect** or **disconnect** button.
+
+```tsx
+
+	return <ConnectButton />;
+}
+```
+
+### Props
+
+All props are optional.
+
+- `connectText = "Connect Wallet"` - The text that displays in the button when the user is not
+  currently connected to a wallet.
+- `walletFilter` - A filter function that receives a wallet instance, and returns a boolean
+  indicating whether the wallet should be displayed in the wallet list. By default, all wallets are
+  displayed.