@mysten/dapp-kit 1.0.5 → 1.0.6

package/docs/sui-client-provider.md

@@ -0,0 +1,196 @@
+# SuiClientProvider
+
+> React provider for managing the active SuiJsonRpcClient in legacy dApp Kit.
+
+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 app 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,117 @@
+# Themes
+
+> Theming API for customizing the appearance of legacy 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
+
+> Legacy React button component for connecting and disconnecting a Sui wallet.
+
+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.

package/docs/wallet-components/ConnectModal.md

@@ -0,0 +1,67 @@
+# ConnectModal
+
+> Legacy React modal component that guides users through connecting their wallet.
+
+ControlledConnectModalExample,
+	UncontrolledConnectModalExample,
+} from '../../../../examples/wallet-components-client';
+
+The `ConnectModal` component opens a modal that guides the user through connecting their wallet to
+the app.
+
+## Controlled example
+
+```tsx
+
+	const currentAccount = useCurrentAccount();
+	const [open, setOpen] = useState(false);
+
+	return (
+		<ConnectModal
+			trigger={
+				<button disabled={!!currentAccount}> {currentAccount ? 'Connected' : 'Connect'}</button>
+			}
+			open={open}
+			onOpenChange={(isOpen) => setOpen(isOpen)}
+		/>
+	);
+}
+```
+
+Click **Connect** to connect your wallet and see the previous code in action:
+
+## Uncontrolled example
+
+```tsx
+
+	const currentAccount = useCurrentAccount();
+
+	return (
+		<ConnectModal
+			trigger={
+				<button disabled={!!currentAccount}> {currentAccount ? 'Connected' : 'Connect'}</button>
+			}
+		/>
+	);
+}
+```
+
+Click **Connect** to connect your wallet and see the previous code in action:
+
+## Controlled props
+
+- `open`: The controlled open state of the dialog.
+- `onOpenChange`: Event handler called when the open state of the dialog changes.
+- `trigger`: The trigger button that opens the dialog.
+- `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.
+
+## Uncontrolled props
+
+- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not
+  need to control its open state.
+- `trigger`: The trigger button that opens the dialog.
+- `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.

package/docs/wallet-hooks/useAccounts.md

@@ -0,0 +1,36 @@
+# useAccounts
+
+> Legacy React hook to list connected wallet accounts authorized by the app.
+
+The `useAccounts` hook retrieves a list of connected accounts the app authorizes.
+
+```ts
+
+function MyComponent() {
+	const accounts = useAccounts();
+
+	return (
+		<div>
+			<ConnectButton />
+			<h2>Available accounts:</h2>
+			{accounts.length === 0 && <div>No accounts detected</div>}
+			<ul>
+				{accounts.map((account) => (
+					<li key={account.address}>- {account.address}</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Account properties
+
+- `address`: The address of the account, corresponding with a public key.
+- `publicKey`: The public key of the account, represented as a `Uint8Array`.
+- `chains`: The chains the account supports.
+- `features`: The features the account supports.
+- `label`: An optional user-friendly descriptive label or name for the account.
+- `icon`: An optional user-friendly icon for the account.

package/docs/wallet-hooks/useAutoConnectWallet.md

@@ -0,0 +1,29 @@
+# useAutoConnectWallet
+
+> Legacy React hook to check the auto-connection status for the last connected wallet.
+
+The `useAutoConnectWallet` hook retrieves the status for the initial wallet auto-connection process.
+
+```ts
+
+function MyComponent() {
+	const autoConnectionStatus = useAutoConnectWallet();
+
+	return (
+		<div>
+			<ConnectButton />
+			<div>Auto-connection status: {autoConnectionStatus}</div>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Auto-connection status properties
+
+- `disabled`: When the auto-connection functionality is disabled.
+- `idle`: When the initial auto-connection attempt hasn't been made yet.
+- `attempted`: When an auto-connection attempt has been made. This means either that there is no
+  previously connected wallet, the previously connected wallet was not found, or that it has
+  successfully connected to a wallet.

package/docs/wallet-hooks/useConnectWallet.md

@@ -0,0 +1,48 @@
+# useConnectWallet
+
+> Legacy React mutation hook to establish a connection with a specific wallet.
+
+The `useConnectWallet` hook is a mutation hook for establishing a connection to a specific wallet.
+
+```ts
+
+function MyComponent() {
+	const wallets = useWallets();
+	const { mutate: connect } = useConnectWallet();
+
+	return (
+		<div style={{ padding: 20 }}>
+			<ConnectButton />
+			<ul>
+				{wallets.map((wallet) => (
+					<li key={wallet.name}>
+						<button
+							onClick={() => {
+								connect(
+									{ wallet },
+									{
+										onSuccess: () => console.log('connected'),
+									},
+								);
+							}}
+						>
+							Connect to {wallet.name}
+						</button>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Connect arguments
+
+- `args`: Arguments passed to the `connect` function of the wallet.
+  - `wallet`: The wallet to connect to.
+  - `accountAddress`: (optional) The address in the wallet to connect to.
+
+- `options`: Options passed the `useMutation` hook from
+  [@tanstack/react-query](https://tanstack.com/query/latest/docs/react/guides/mutations).

package/docs/wallet-hooks/useCurrentAccount.md

@@ -0,0 +1,36 @@
+# useCurrentAccount
+
+> Legacy React hook to get the currently selected wallet account.
+
+The `useCurrentAccount` hook retrieves the wallet account that is currently selected, if one exists.
+
+```ts
+
+function MyComponent() {
+	const account = useCurrentAccount();
+
+	return (
+		<div>
+			<ConnectButton />
+			{!account && <div>No account connected</div>}
+			{account && (
+				<div>
+					<h2>Current account:</h2>
+					<div>Address: {account.address}</div>
+				</div>
+			)}
+		</div>
+	);
+}
+```
+
+## Example
+
+## Account properties
+
+- `address`: The address of the account, corresponding with a public key.
+- `publicKey`: The public key of the account, represented as a `Uint8Array`.
+- `chains`: The chains the account supports.
+- `features`: The features the account supports.
+- `label`: An optional user-friendly descriptive label or name for the account.
+- `icon`: An optional user-friendly icon for the account.

package/docs/wallet-hooks/useCurrentWallet.md

@@ -0,0 +1,59 @@
+# useCurrentWallet
+
+> Legacy React hook to get the currently connected wallet and connection status.
+
+The `useCurrentWallet` hook retrieves the wallet that is currently connected to the app, if one
+exists.
+
+```ts
+
+function MyComponent() {
+	const { currentWallet, connectionStatus } = useCurrentWallet();
+
+	return (
+		<div>
+			<ConnectButton />
+			{connectionStatus === 'connected' ? (
+				<div>
+					<h2>Current wallet:</h2>
+					<div>Name: {currentWallet.name}</div>
+					<div>
+						Accounts:
+						<ul>
+							{currentWallet.accounts.map((account) => (
+								<li key={account.address}>- {account.address}</li>
+							))}
+						</ul>
+					</div>
+				</div>
+			) : (
+				<div>Connection status: {connectionStatus}</div>
+			)}
+		</div>
+	);
+}
+```
+
+## Example
+
+## Wallet properties
+
+- `name`: The name of the wallet.
+- `version`: The version of the wallet as a string.
+- `icon`: A data URL of the wallet icon as an SVG.
+- `accounts`: An array of accounts that are available in the wallet.
+- `features`: An object with all the
+  [`wallet-standard`](https://github.com/wallet-standard/wallet-standard) features implemented by
+  the wallet.
+- `chains`: An array of chain identifiers that the wallet supports.
+
+## Connection status properties
+
+- `connectionStatus`
+  - `disconnected`: When no wallet is connected to the app.
+  - `connecting`: When a wallet connection attempt is in progress.
+  - `connected`: When a wallet is connected to the app.
+
+- `isDisconnected`: A derived boolean from the status variable above, provided for convenience.
+- `isConnecting`: A derived boolean from the status variable above, provided for convenience.
+- `isConnected`: A derived boolean from the status variable above, provided for convenience.

package/docs/wallet-hooks/useDisconnectWallet.md

@@ -0,0 +1,26 @@
+# useDisconnectWallet
+
+> Legacy React mutation hook to disconnect from the currently connected wallet.
+
+The `useDisconnectWallet` hook is a mutation hook for disconnecting from an active wallet
+connection, if currently connected.
+
+```ts
+
+function MyComponent() {
+	const { mutate: disconnect } = useDisconnectWallet();
+	return (
+		<div>
+			<ConnectButton />
+
+			<button onClick={() => disconnect()}>Disconnect</button>
+		</div>
+	);
+}
+```
+
+## Example
+
+## Arguments
+
+There are no arguments for `useDisconnectWallet`.