@mysten/dapp-kit-react 1.1.0 → 2.0.1

package/docs/react/hooks/use-current-account.md

@@ -0,0 +1,33 @@
+# useCurrentAccount
+
+> React hook to get the current wallet account
+
+The `useCurrentAccount` hook provides access to the currently selected account.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [DAppKitProvider](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const account = useCurrentAccount();
+
+	if (!account) {
+		return <div>No account selected</div>;
+	}
+
+	return (
+		<div>
+			<p>Address: {account.address}</p>
+			<p>Label: {account.label}</p>
+		</div>
+	);
+}
+```
+
+## Return Value
+
+```tsx
+UiWalletAccount | null;
+```

package/docs/react/hooks/use-current-client.md

@@ -0,0 +1,36 @@
+# useCurrentClient
+
+> React hook to get the current Sui client instance
+
+The `useCurrentClient` hook provides access to the blockchain client instance for the current
+network.
+
+> **Note:** By default, this returns a `SuiClient` instance when using the standard setup. However,
+> the dApp Kit supports any client that implements the Sui core API, making it flexible for
+> different blockchain implementations.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [DAppKitProvider](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const client = useCurrentClient();
+
+	const handleQuery = async () => {
+		const balance = await client.getBalance({
+			owner: '0x...',
+		});
+		console.log(balance);
+	};
+
+	return <button onClick={handleQuery}>Check Balance</button>;
+}
+```
+
+## Return Value
+
+```tsx
+SuiClient;
+```

package/docs/react/hooks/use-current-network.md

@@ -0,0 +1,28 @@
+# useCurrentNetwork
+
+> React hook to get the current network
+
+The `useCurrentNetwork` hook provides access to the currently selected network.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [DAppKitProvider](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const network = useCurrentNetwork();
+
+	return (
+		<div>
+			<p>Current network: {network}</p>
+		</div>
+	);
+}
+```
+
+## Return Value
+
+```tsx
+string;
+```

package/docs/react/hooks/use-current-wallet.md

@@ -0,0 +1,36 @@
+# useCurrentWallet
+
+> React hook to get the current wallet connection
+
+The `useCurrentWallet` hook provides access to the currently connected wallet.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [DAppKitProvider](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const wallet = useCurrentWallet();
+
+	if (!wallet) {
+		return <div>No wallet connected</div>;
+	}
+
+	return (
+		<div>
+			<p>Wallet: {wallet.name}</p>
+			<p>
+				Icon: <img src={wallet.icon} alt={wallet.name} />
+			</p>
+			<p>Accounts: {wallet.accounts.length}</p>
+		</div>
+	);
+}
+```
+
+## Return Value
+
+```tsx
+UiWallet | null;
+```

package/docs/react/hooks/use-dapp-kit.md

@@ -0,0 +1,100 @@
+# useDAppKit
+
+> React hook to access the full dApp Kit instance
+
+The `useDAppKit` hook provides direct access to the dApp Kit instance within React components,
+enabling you to call actions and access the underlying functionality.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [DAppKitProvider](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const dAppKit = useDAppKit();
+
+	async function handleConnect() {
+		try {
+			await dAppKit.connectWallet({ wallet });
+			console.log('Connected successfully');
+		} catch (error) {
+			console.error('Connection failed:', error);
+		}
+	}
+
+	return <button onClick={handleConnect}>Connect Wallet</button>;
+}
+```
+
+## Return Value
+
+```ts
+{
+    // Actions
+    connectWallet: (args: { wallet: UiWallet; account?: UiWalletAccount }) => Promise<{ accounts: UiWalletAccount[]; }>;
+    disconnectWallet: () => Promise<void>;
+    switchAccount: (args: { account: UiWalletAccount }) => Promise<void>;
+    switchNetwork: (network: string) => void;
+    signTransaction: (args: { transaction: Transaction | string; signal?: AbortSignal }) => Promise<SignedTransaction>;
+    signAndExecuteTransaction: (args: { transaction: Transaction | string; signal?: AbortSignal }) => Promise<TransactionResult>;
+    signPersonalMessage: (args: { message: Uint8Array }) => Promise<SignedPersonalMessage>;
+
+    // Properties
+    networks: string[];
+    stores:  {
+        $wallets: DAppKitStores['$compatibleWallets'];
+        $connection: DAppKitStores['$connection'];
+        $currentNetwork: ReadableAtom<TNetworks[number]>;
+        $currentClient: ReadableAtom<Client>;
+    };
+    getClient: (network?: string) => Client;
+}
+```
+
+## Examples
+
+### Transaction Execution
+
+```tsx
+
+	const dAppKit = useDAppKit();
+
+	async function handleTransfer() {
+		const tx = new Transaction();
+		tx.transferObjects([tx.object('0x123...')], '0xrecipient...');
+
+		try {
+			const result = await dAppKit.signAndExecuteTransaction({
+				transaction: tx,
+			});
+
+			if (result.FailedTransaction) {
+				throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+			}
+
+			console.log('Transaction digest:', result.Transaction.digest);
+		} catch (error) {
+			console.error('Transaction failed:', error);
+		}
+	}
+
+	return <button onClick={handleTransfer}>Transfer</button>;
+}
+```
+
+### Subscribing to State Changes
+
+```tsx
+
+	const dAppKit = useDAppKit();
+	useEffect(() => {
+		// Subscribe directly to connection store changes
+		const unsubscribe = dAppKit.stores.$connection.subscribe((connection) => {
+			console.log('Connection status:', connection.status);
+		});
+		return unsubscribe;
+	}, [dAppKit]);
+	return null;
+}
+```

package/docs/react/hooks/use-wallet-connection.md

@@ -0,0 +1,48 @@
+# useWalletConnection
+
+> React hook to manage wallet connection and disconnection
+
+The `useWalletConnection` hook provides access to the current wallet connection status and
+information.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [DAppKitProvider](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const connection = useWalletConnection();
+
+	if (connection.status === 'disconnected') {
+		return <div>Please connect your wallet</div>;
+	}
+
+	if (connection.status === 'connecting') {
+		return <div>Connecting...</div>;
+	}
+
+	// status === 'connected'
+	return (
+		<div>
+			<p>Connected to: {connection.wallet.name}</p>
+			<p>Address: {connection.account.address}</p>
+		</div>
+	);
+}
+```
+
+## Return Value
+
+```tsx
+{
+	status: 'disconnected' | 'connecting' | 'reconnecting' | 'connected';
+	wallet: UiWallet | null;
+	account: UiWalletAccount | null;
+	supportedIntents: string[];
+	isConnected: boolean;
+	isConnecting: boolean;
+	isReconnecting: boolean;
+	isDisconnected: boolean;
+}
+```

package/docs/react/hooks/use-wallets.md

@@ -0,0 +1,33 @@
+# useWallets
+
+> React hook to list available wallets
+
+The `useWallets` hook provides access to all available wallets.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [DAppKitProvider](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const wallets = useWallets();
+
+	return (
+		<div>
+			{wallets.map((wallet) => (
+				<div key={wallet.name}>
+					<img src={wallet.icon} alt={wallet.name} />
+					<span>{wallet.name}</span>
+				</div>
+			))}
+		</div>
+	);
+}
+```
+
+## Return Value
+
+```tsx
+UiWallet[]
+```

package/docs/state.md

@@ -0,0 +1,168 @@
+# State
+
+> Access and subscribe to wallet connection state in dApp Kit
+
+The Sui dApp Kit SDK uses [nanostores](https://github.com/nanostores/nanostores) for state
+management, providing a lightweight, framework-agnostic solution that works across React, Vue,
+Vanilla JavaScript, and other frameworks.
+
+## Available Stores
+
+The dApp Kit exposes four reactive stores that you can subscribe to:
+
+- **`$connection`** - Current wallet connection state
+- **`$currentNetwork`** - Currently selected network
+- **`$currentClient`** - Client instance for the current network
+- **`$wallets`** - List of available wallets
+
+## Accessing Stores
+
+All stores are available through the `dAppKit.stores` property:
+
+```typescript
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+// Access stores
+const connection = dAppKit.stores.$connection.get();
+const currentNetwork = dAppKit.stores.$currentNetwork.get();
+const client = dAppKit.stores.$currentClient.get();
+const wallets = dAppKit.stores.$wallets.get();
+```
+
+## Subscribing to State Changes
+
+Subscribe to any store to react to state changes:
+
+```typescript
+// Subscribe to connection changes
+const unsubscribe = dAppKit.stores.$connection.subscribe((connection) => {
+	if (connection.isConnected && connection.wallet && connection.account) {
+		console.log('Connected to:', connection.wallet.name);
+		console.log('Account:', connection.account.address);
+	} else {
+		console.log('Not connected');
+	}
+});
+
+// Clean up subscription when done
+unsubscribe();
+```
+
+## Store Details
+
+### Connection Store (`$connection`)
+
+Contains the current wallet connection state with status flags:
+
+```typescript
+const connection = dAppKit.stores.$connection.get();
+
+// Connection has these properties:
+// - wallet: UiWallet | null
+// - account: UiWalletAccount | null
+// - status: 'connected' | 'connecting' | 'reconnecting' | 'disconnected'
+// - supportedIntents: string[]
+// - isConnected: boolean
+// - isConnecting: boolean
+// - isReconnecting: boolean
+// - isDisconnected: boolean
+```
+
+Example usage:
+
+```typescript
+const connection = dAppKit.stores.$connection.get();
+
+if (connection.isConnected && connection.wallet && connection.account) {
+	console.log('Address:', connection.account.address);
+	console.log('Wallet:', connection.wallet.name);
+	console.log('Available accounts:', connection.wallet.accounts);
+}
+```
+
+### Current Network Store (`$currentNetwork`)
+
+Contains the currently selected network as a string:
+
+```typescript
+const currentNetwork = dAppKit.stores.$currentNetwork.get(); // 'mainnet' | 'testnet' | ...
+
+// Subscribe to network changes
+dAppKit.stores.$currentNetwork.subscribe((network) => {
+	console.log('Switched to network:', network);
+});
+```
+
+Note: This store is read-only. Use `dAppKit.switchNetwork()` to change networks.
+
+### Current Client Store (`$currentClient`)
+
+Contains the SuiClient instance for the current network:
+
+```typescript
+const client = dAppKit.stores.$currentClient.get();
+
+// Use the client to query the blockchain
+const balance = await client.getBalance({
+	owner: '0x...',
+});
+```
+
+Note: This store automatically updates when the network changes.
+
+### Wallets Store (`$wallets`)
+
+Contains the list of available wallets:
+
+```typescript
+const wallets = dAppKit.stores.$wallets.get();
+
+wallets.forEach((wallet) => {
+	console.log('Wallet:', wallet.name);
+	console.log('Icon:', wallet.icon);
+});
+```
+
+## Subscribing to State Changes
+
+You can subscribe directly to stores:
+
+```typescript
+// Subscribe to connection changes
+dAppKit.stores.$connection.subscribe((connection) => {
+	const statusElement = document.getElementById('connection-status');
+	if (statusElement === null) return;
+	if (connection.isConnected && connection.account) {
+		statusElement.textContent = `Connected: ${connection.account.address}`;
+	} else {
+		statusElement.textContent = 'Not connected';
+	}
+});
+
+// Subscribe to network changes
+dAppKit.stores.$currentNetwork.subscribe((network) => {
+	const networkElement = document.getElementById('current-network');
+	if (networkElement === null) return;
+	networkElement.textContent = `Network: ${network}`;
+});
+```
+
+## React
+
+React users can use the [provided hooks](./react/hooks/use-wallet-connection) instead of direct
+store access.
+
+## Properties
+
+Besides stores, some values are available as direct properties:
+
+```typescript
+// Get available networks (not a store, just a property)
+const networks = dAppKit.networks; // ['mainnet', 'testnet', ...]
+
+// Get client for specific network
+const mainnetClient = dAppKit.getClient('mainnet');
+const currentClient = dAppKit.getClient(); // Current network's client
+```

package/docs/theming.md

@@ -0,0 +1,196 @@
+# Theming
+
+> Customize the appearance of dApp Kit UI components
+
+The dApp Kit web components use a theming system compatible with
+[shadcn/ui](https://ui.shadcn.com/docs/theming). Components are customized using CSS custom
+properties (CSS variables), allowing you to match them to your application's design system.
+
+> **Note:** **shadcn/ui Compatibility**: The dApp Kit uses the same CSS custom property naming
+> convention as shadcn/ui. If your application already uses shadcn/ui themes, the dApp Kit
+> components will automatically inherit your theme. You can also use
+> [shadcn/ui's theme builder](https://ui.shadcn.com/themes) to create custom themes.
+
+## CSS Custom Properties
+
+All dApp Kit web components support the following CSS custom properties:
+
+### Colors
+
+These color variables follow the shadcn/ui naming convention. Colors can be defined using any valid
+CSS color format (hex, rgb, hsl, oklch, etc.).
+
+- **`--background`** - Background color of the component. Used as the default background for UI
+  elements.
+- **`--foreground`** - Foreground color of the component. Used as the default text color.
+- **`--primary`** - Primary color used for interactive elements such as buttons and links.
+- **`--primary-foreground`** - Text or icon color placed on top of primary elements.
+- **`--secondary`** - Secondary color used for less prominent interactive elements.
+- **`--secondary-foreground`** - Text or icon color placed on top of secondary elements.
+- **`--border`** - Border color for UI elements.
+- **`--accent`** - Accent color used for highlights and decorative elements.
+- **`--accent-foreground`** - Text or icon color placed on top of accent elements.
+- **`--muted`** - Background color for subtle or muted UI elements (e.g., placeholders, disabled
+  states).
+- **`--muted-foreground`** - Text or icon color for muted UI elements.
+- **`--popover`** - Background color for floating elements such as popovers, dropdowns, or tooltips.
+- **`--popover-foreground`** - Text or icon color inside popover elements.
+- **`--ring`** - Color used for focus rings (visible focus indicators on interactive elements).
+
+### Typography
+
+- **`--font-sans`** - Font family used for text content.
+- **`--font-weight-medium`** - Medium font weight for text (typically used for buttons and
+  interactive elements).
+- **`--font-weight-semibold`** - Semibold font weight for text (typically used for headings or
+  emphasized text).
+
+### Layout
+
+- **`--radius`** - Border radius used for UI elements.
+
+## Usage
+
+### Global Theming
+
+Apply custom properties to affect all dApp Kit components:
+
+```css
+:root {
+	--primary: #4f46e5;
+	--primary-foreground: #ffffff;
+	--background: #ffffff;
+	--foreground: #0f172a;
+	--border: #e2e8f0;
+	--radius: 0.5rem;
+	--font-sans: 'Inter', sans-serif;
+}
+```
+
+### Component-Specific Theming
+
+Target specific components:
+
+```css
+mysten-dapp-kit-connect-button {
+	--primary: #10b981;
+	--primary-foreground: #ffffff;
+	--radius: 0.75rem;
+}
+
+mysten-dapp-kit-connect-modal {
+	--background: #f8fafc;
+	--popover: #ffffff;
+}
+```
+
+### Dark Mode
+
+Implement dark mode by overriding the custom properties:
+
+```css
+:root {
+	--background: #ffffff;
+	--foreground: #0f172a;
+	--primary: #4f46e5;
+	--border: #e2e8f0;
+}
+
+@media (prefers-color-scheme: dark) {
+	:root {
+		--background: #0f172a;
+		--foreground: #f1f5f9;
+		--primary: #818cf8;
+		--border: #334155;
+	}
+}
+```
+
+Or use a class-based approach:
+
+```css
+.light-theme {
+	--background: #ffffff;
+	--foreground: #0f172a;
+}
+
+.dark-theme {
+	--background: #0f172a;
+	--foreground: #f1f5f9;
+}
+```
+
+```tsx
+<div className={isDark ? 'dark-theme' : 'light-theme'}>
+	<ConnectButton />
+</div>
+```
+
+## Example: Complete Theme
+
+Here's a complete theme example matching a custom design system:
+
+```css
+:root {
+	/* Colors */
+	--background: hsl(0 0% 100%);
+	--foreground: hsl(222.2 84% 4.9%);
+	--primary: hsl(221.2 83.2% 53.3%);
+	--primary-foreground: hsl(210 40% 98%);
+	--secondary: hsl(210 40% 96.1%);
+	--secondary-foreground: hsl(222.2 47.4% 11.2%);
+	--accent: hsl(210 40% 96.1%);
+	--accent-foreground: hsl(222.2 47.4% 11.2%);
+	--muted: hsl(210 40% 96.1%);
+	--muted-foreground: hsl(215.4 16.3% 46.9%);
+	--border: hsl(214.3 31.8% 91.4%);
+	--popover: hsl(0 0% 100%);
+	--popover-foreground: hsl(222.2 84% 4.9%);
+	--ring: hsl(221.2 83.2% 53.3%);
+
+	/* Typography */
+	--font-sans:
+		system-ui, -apple-system, 'Segoe UI', 'Roboto', 'Ubuntu', 'Cantarell', 'Noto Sans', sans-serif;
+	--font-weight-medium: 500;
+	--font-weight-semibold: 600;
+
+	/* Layout */
+	--radius: 0.5rem;
+}
+```
+
+## Framework Integration
+
+### React
+
+```tsx
+
+	return <ConnectButton />;
+}
+```
+
+### Vue
+
+```vue
+<template>
+	<mysten-dapp-kit-connect-button :instance="dAppKit" />
+</template>
+
+<style>
+@import './theme.css';
+</style>
+```
+
+### Vanilla JavaScript
+
+```html
+<!doctype html>
+<html>
+	<head>
+		<link rel="stylesheet" href="theme.css" />
+	</head>
+	<body>
+		<mysten-dapp-kit-connect-button></mysten-dapp-kit-connect-button>
+	</body>
+</html>
+```