@mysten/dapp-kit-react 1.1.0 → 2.0.1

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

@@ -0,0 +1,87 @@
+# Connect Button
+
+> Framework-agnostic web component for wallet connection
+
+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,176 @@
+# Connect Modal
+
+> Framework-agnostic web component for wallet selection
+
+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,12 +2,13 @@
   "name": "@mysten/dapp-kit-react",
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "React bindings for @mysten/dapp-kit-core",
-  "version": "1.1.0",
+  "version": "2.0.1",
   "license": "Apache-2.0",
   "files": [
     "LICENSE",
     "README.md",
     "dist",
+    "docs",
     "src"
   ],
   "type": "module",
@@ -18,6 +19,11 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.mts",
+      "import": "./dist/ui.mjs",
+      "default": "./dist/ui.mjs"
     }
   },
   "repository": {
@@ -40,7 +46,7 @@
     "@lit/react": "^1.0.8",
     "@nanostores/react": "^1.0.0",
     "nanostores": "^1.1.0",
-    "@mysten/dapp-kit-core": "^1.1.0"
+    "@mysten/dapp-kit-core": "^1.2.0"
   },
   "peerDependencies": {
     "@types/react": ">=17.0.0",
@@ -49,6 +55,7 @@
   "scripts": {
     "clean": "rm -rf tsconfig.tsbuildinfo ./dist",
     "build": "pnpm typecheck && tsdown",
+    "build:docs": "tsx ../../../docs/scripts/build-docs.ts",
     "typecheck": "tsc --noEmit",
     "dev": "tsdown --watch",
     "prettier:check": "prettier -c --ignore-unknown .",

package/src/index.ts

@@ -3,12 +3,6 @@
 
 export * from '@mysten/dapp-kit-core';
 
-export { ConnectButton } from './components/ConnectButton.js';
-export type { ConnectButtonProps } from './components/ConnectButton.js';
-
-export { ConnectModal } from './components/ConnectModal.js';
-export type { ConnectModalProps } from './components/ConnectModal.js';
-
 export { DAppKitProvider, DAppKitContext } from './components/DAppKitProvider.js';
 export type { DAppKitProviderProps } from './components/DAppKitProvider.js';
 

package/src/ui.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export { ConnectButton } from './components/ConnectButton.js';
+export type { ConnectButtonProps } from './components/ConnectButton.js';
+
+export { ConnectModal } from './components/ConnectModal.js';
+export type { ConnectModalProps } from './components/ConnectModal.js';