@mysten/dapp-kit-react 2.0.2 → 2.0.3

package/docs/state.md

@@ -0,0 +1,169 @@
+# 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);
+});
+```
+
+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...',
+});
+```
+
+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, and others).
+
+- **`--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 (for example, placeholders and
+  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>
+```

package/docs/web-components/connect-button.md

@@ -0,0 +1,89 @@
+# Connect Button
+
+> Framework-agnostic web component providing a complete wallet connection UI for Sui dApps.
+
+The `<mysten-dapp-kit-connect-button>` Web Component provides a complete wallet connection UI. It
+displays a "Connect Wallet" button when no wallet is connected, and shows the connected account with
+a menu when a wallet is active.
+
+> Auto-connect is enabled by default and will attempt to restore the previous wallet connection on
+> page reload. This provides a seamless user experience but can be
+> [disabled](../dapp-kit-instance#disabling-auto-connect) if needed.
+
+## Basic usage
+
+### Vanilla
+
+```html
+<mysten-dapp-kit-connect-button></mysten-dapp-kit-connect-button>
+
+<script>
+	const button = document.querySelector('mysten-dapp-kit-connect-button');
+	   button!.instance = dAppKit;
+</script>
+```
+
+### Vue
+
+```vue
+<script setup>
+
+</script>
+
+<template>
+	<mysten-dapp-kit-connect-button :instance="dAppKit" />
+</template>
+```
+
+### React
+
+DApp Kit React bindings provide a [React wrapper](../react/components/connect-button) for the
+button.
+
+## Features
+
+The connect button component automatically handles:
+
+- **Wallet Connection**: Opens a modal to select and connect a wallet
+- **Account Display**: Shows the connected account address
+- **Account Switching**: Provides a menu to switch between multiple accounts when connected
+- **Disconnection**: Includes a disconnect option in the menu
+
+## Properties
+
+- **instance:** The dApp Kit instance
+- **modalOptions** (optional) - Configuration options for the connect modal
+  - `filterFn`: Function to filter available wallets
+  - `sortFn`: Function to sort available wallets
+
+## Custom button text
+
+Use the default slot to customize the button text when not connected:
+
+```html
+<mysten-dapp-kit-connect-button>
+	<span>Sign In</span>
+</mysten-dapp-kit-connect-button>
+```
+
+## Modal integration
+
+The connect button automatically manages its own modal. You don't need to add a separate
+`<mysten-dapp-kit-connect-modal>` component when using the connect button.
+
+## Connected state
+
+When a wallet is connected, the button transforms into an account menu that displays:
+
+- Account address (truncated)
+- SUI balance
+- Network indicator
+- Menu options for:
+  - Switching accounts (if multiple accounts available)
+  - Managing connection
+  - Disconnecting
+
+## Server-side rendering (SSR)
+
+The `<mysten-dapp-kit-connect-button>` Web Component can be only client-side rendered, as wallets
+are detected in the browser. For Next.js guide see [here](../getting-started/next-js).

package/docs/web-components/connect-modal.md

@@ -0,0 +1,177 @@
+# Connect Modal
+
+> Framework-agnostic web component for wallet selection and connection in Sui dApps.
+
+The `<mysten-dapp-kit-connect-modal>` Web Component provides a modal dialog for wallet connection.
+While most apps should use the [`Connect Button`](./connect-button) which includes an integrated
+modal, the standalone modal is useful for advanced scenarios requiring custom trigger mechanisms.
+
+## When to use
+
+Use the standalone modal when you need:
+
+- **Custom trigger elements:** Menu items, keyboard shortcuts, or other non-button triggers
+- **Complex UI flows:** Integration into existing navigation or custom wallet management interfaces
+- **Programmatic control:** Opening the modal based on application logic or user actions
+- **Multiple triggers:** Different parts of your UI that can open the same modal
+
+For standard wallet connection with a button, use the [Connect Button](./connect-button) component
+instead.
+
+## Basic usage
+
+### Vanilla
+
+```html
+<button id="custom-trigger">Open Wallet Selector</button>
+<mysten-dapp-kit-connect-modal></mysten-dapp-kit-connect-modal>
+
+<script>
+	import { createDAppKit } from '@mysten/dapp-kit-core';
+	import { SuiGrpcClient } from '@mysten/sui/grpc';
+
+	const GRPC_URLS = {
+	    mainnet: 'https://fullnode.mainnet.sui.io:443',
+	    testnet: 'https://fullnode.testnet.sui.io:443',
+	};
+
+	const dAppKit = createDAppKit({
+	    enableBurnerWallet: import.meta.env.DEV,
+	    networks: ['mainnet', 'testnet'],
+	    defaultNetwork: 'testnet',
+	    createClient(network) {
+	        return new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] });
+	    },
+	});
+
+	const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+	modal!.instance = dAppKit;
+
+	const trigger = document.getElementById('custom-trigger');
+	trigger?.addEventListener('click', () => {
+	    modal!.show();
+	});
+</script>
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+
+const modalRef = ref();
+const isModalOpen = ref(false);
+
+const openModal = () => {
+	// Using property binding
+	isModalOpen.value = true;
+	// Or using method
+	modalRef.value.show();
+};
+</script>
+
+<template>
+	<!-- Custom trigger -->
+	<button @click="openModal">Select Wallet</button>
+
+	<!-- Modal component -->
+	<mysten-dapp-kit-connect-modal
+		ref="modalRef"
+		:instance="dAppKit"
+		:open="isModalOpen"
+		@closed="isModalOpen = false"
+	/>
+</template>
+```
+
+### React
+
+DApp Kit React bindings provide a [React wrapper](../react/components/connect-modal) for the modal.
+
+## Properties
+
+- **instance:** The dApp Kit instance
+- **open:** Boolean to control modal visibility programmatically
+- **filterFn** (optional) - Function to filter available wallets
+  - Type: `(wallet: UiWallet, index: number, array: UiWallet[]) => boolean`
+- **sortFn** (optional) - Function to sort available wallets
+  - Type: `(a: UiWallet, b: UiWallet) => number`
+
+## Methods
+
+### show()
+
+Opens the modal programmatically:
+
+```js
+const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+await modal?.show();
+```
+
+### close(returnValue: string)
+
+Closes the modal with an optional return value:
+
+```js
+const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+await modal?.close('user-cancelled');
+```
+
+## Events
+
+The modal fires several events during its lifecycle:
+
+- **open:** Fired before the modal opens (cancelable)
+- **opened:** Fired after the modal has fully opened
+- **close:** Fired before the modal closes (cancelable)
+- **closed:** Fired after the modal has fully closed
+- **cancel:** Fired when clicking backdrop or pressing Escape (cancelable)
+
+```js
+const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+
+modal?.addEventListener('open', (event) => {
+	console.log('Modal is about to open');
+	// Prevent opening if needed
+	// event.preventDefault();
+});
+
+modal?.addEventListener('opened', () => {
+	console.log('Modal is now open');
+});
+
+modal?.addEventListener('closed', () => {
+	console.log('Modal has closed');
+});
+
+modal?.addEventListener('cancel', (event) => {
+	console.log('User clicked backdrop or pressed Escape');
+});
+```
+
+## Examples
+
+### Programmatic control
+
+```js
+const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+modal.instance = dAppKit;
+
+// Open modal when user tries to perform an action that requires connection
+async function performAction() {
+	const connection = dAppKit.stores.$connection.get();
+
+	if (!connection.account) {
+		await modal.show();
+		// Wait for connection or cancellation
+		return;
+	}
+
+	// Proceed with action...
+}
+```
+
+## Server-side rendering (SSR)
+
+The `<mysten-dapp-kit-connect-modal>` Web Component can be only client-side rendered, as wallets are
+detected in the browser. For Next.js guide see [here](../getting-started/next-js).

package/package.json

@@ -2,7 +2,7 @@
   "name": "@mysten/dapp-kit-react",
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "React bindings for @mysten/dapp-kit-core",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "license": "Apache-2.0",
   "files": [
     "LICENSE",
@@ -44,7 +44,7 @@
     "@lit/react": "^1.0.8",
     "@nanostores/react": "^1.0.0",
     "nanostores": "^1.1.0",
-    "@mysten/dapp-kit-core": "^1.3.1"
+    "@mysten/dapp-kit-core": "^1.3.2"
   },
   "peerDependencies": {
     "@types/react": ">=17.0.0",