WizardConnect/packages/react/README.md

# @wizardconnect/react

React components and hooks for integrating WizardConnect into dapps.

## Installation

```bash
npm install @wizardconnect/react @wizardconnect/core @wizardconnect/dapp
```

React 18+ is required as a peer dependency.

## Components

### WizardConnectQRDialog

A portal-based modal dialog that displays a WizardConnect QR code for wallet pairing. Uses inline styles for framework independence (no Tailwind or CSS framework required).

```tsx
import { WizardConnectQRDialog } from "@wizardconnect/react";

<WizardConnectQRDialog
  show={showDialog}
  onClose={() => setShowDialog(false)}
  uri={connection.uri}
  qrUri={connection.qrUri}
  logoUrl="/my-logo.png"
  theme={{
    dialogBackground: "#1e293b",
    headerBackground: "#1e293b",
  }}
/>;
```

**Props:**

| Prop        | Type                    | Default                              | Description                                         |
| ----------- | ----------------------- | ------------------------------------ | --------------------------------------------------- |
| `show`      | `boolean`               | _required_                           | Whether the dialog is visible                       |
| `onClose`   | `() => void`            | _required_                           | Called when the user clicks close or the backdrop   |
| `uri`       | `string`                | _required_                           | Human-readable URI to display (`wiz://...`)         |
| `qrUri`     | `string`                | _required_                           | Alphanumeric-safe URI for QR encoding (`WIZ://...`) |
| `onCopy`    | `(uri: string) => void` | `navigator.clipboard.writeText`      | Called when copy button is clicked                  |
| `theme`     | `WizardConnectQRTheme`  | dark theme defaults                  | Color overrides                                     |
| `title`     | `string`                | `"WizardConnect"`                    | Dialog title                                        |
| `subtitle`  | `string`                | `"Scan with your wallet to connect"` | Subtitle text                                       |
| `logoUrl`   | `string`                | none                                 | Logo for the header                                 |
| `className` | `string`                | none                                 | Additional CSS class on the outermost container     |

### AlphanumericQRCode

A standalone canvas-based QR code renderer. Uses Alphanumeric mode with error correction level H (30% recovery) to tolerate a center logo overlay.

```tsx
import { AlphanumericQRCode } from "@wizardconnect/react";

<AlphanumericQRCode
  value="WIZ://..."
  size={280}
  foreground="#1e2a4a"
  background="#ffffff"
  logoUrl="/logo.png"
/>;
```

## Hooks

### useWizardConnect

Encapsulates the full WizardConnect relay lifecycle: relay initiation, `DappConnectionManager` management, key exchange events, session persistence, and auto-reconnect.

```tsx
import { useWizardConnect, WizardConnectQRDialog } from "@wizardconnect/react";

function ConnectButton() {
  const {
    state, // "idle" | "connecting" | "connected" | "disconnected"
    manager, // DappConnectionManager (null until connect())
    uri, // connection URI (null until connect())
    qrUri, // QR-safe URI (null until connect())
    walletName, // wallet name (null until walletready)
    walletIcon, // wallet icon (null until walletready)
    connect, // () => boolean — initiate a new connection
    disconnect, // () => Promise<void> — disconnect and clean up
    error, // string | null — error message
  } = useWizardConnect({
    dappName: "My Dapp",
    dappIcon: "https://example.com/icon.png",
  });

  return (
    <>
      {state === "idle" && <button onClick={connect}>Connect</button>}
      {state === "connected" && <span>Connected to {walletName}</span>}

      {uri && qrUri && (
        <WizardConnectQRDialog
          show={state === "connecting"}
          onClose={disconnect}
          uri={uri}
          qrUri={qrUri}
        />
      )}
    </>
  );
}
```

**Options:**

| Option           | Type       | Default                   | Description                                |
| ---------------- | ---------- | ------------------------- | ------------------------------------------ |
| `dappName`       | `string`   | none                      | Display name sent in `dapp_ready`          |
| `dappIcon`       | `string`   | none                      | Icon URL sent in `dapp_ready`              |
| `relayUrls`      | `string[]` | default relay             | Explicit relay WebSocket URLs              |
| `sessionKey`     | `string`   | `"wizardconnect-session"` | localStorage key for session persistence   |
| `persistSession` | `boolean`  | `true`                    | Whether to save session for auto-reconnect |

**Using the `manager`:**

After `state` becomes `"connected"`, use `manager` to build your app-specific wallet adapter. The manager provides:

- `getPubkey(childIndex, addressIndex)` — derive pubkeys from xpubs
- `sendSignRequest(request)` — request transaction signatures
- `sendSignCancel(sequence)` — cancel an in-flight sign request
- `on("walletready", callback)` — listen for wallet handshake completion

See the [`@wizardconnect/dapp` documentation](../../docs/dapp.md) for the full `DappConnectionManager` API.

## Theme customization

All colors in `WizardConnectQRDialog` can be overridden via the `theme` prop:

```tsx
const myTheme: WizardConnectQRTheme = {
  backdropColor: "rgba(0,0,0,0.5)",
  dialogBackground: "#1a1f2e",
  headerBackground: "#1a1f2e",
  titleColor: "#ffffff",
  subtitleColor: "#9ca3af",
  qrForeground: "#1e2a4a",
  qrBackground: "#ffffff",
  uriRowBackground: "rgba(31,41,55,0.6)",
  uriTextColor: "#9ca3af",
  borderColor: "#374151",
  closeButtonColor: "#9ca3af",
  copyButtonColor: "#9ca3af",
  logoUrl: "/my-qr-logo.png",
  qrSize: 280,
};
```

## License

LGPL-3.0-or-later. See [LICENSE](../../LICENSE).