npm package: @persistenceone/interop-widget
Description: reusable React widget component
Latest version: 0.0.16

# Interop Widget

A React widget for cross-chain asset bridging with customizable themes, default route configuration, and advanced UI components.

## Installation

```bash
npm install @persistenceone/interop-widget
```

## Basic Usage

```tsx
import { InteropWidget } from '@persistenceone/interop-widget';
import '@persistenceone/interop-widget/style.css';

// Use with default theme
<InteropWidget />

// Use with custom theme
<InteropWidget theme={customTheme} />

// Use with default route configuration
<InteropWidget defaultRouteConfig={routeConfig} />

// Use with both theme and route config
<InteropWidget 
  theme={customTheme} 
  defaultRouteConfig={routeConfig} 
/>
```

## Features

- **Cross-chain bridging** - Seamless asset transfers between chains
- **Customizable themes** - Light, dark, and custom themes
- **Default route configuration** - Pre-select source/destination chains and tokens
- **Advanced UI components** - Tooltip, Modal, Toast, and more
- **CSS isolation** - No conflicts with host applications
- **TypeScript support** - Full type safety
- **Responsive design** - Works on all screen sizes

## Tailwind CSS with Prefix

This widget uses **Tailwind CSS v3** with the `iw-` prefix to prevent conflicts with host applications. All widget styles are prefixed with `iw-` to ensure complete isolation.

### Benefits:

- **No CSS conflicts** - All classes are prefixed with `iw-`
- **Works with any Tailwind version** - v1, v2, v3, v4
- **Works with any CSS framework** - Bootstrap, Material-UI, etc.
- **Self-contained styling** - Widget styles don't interfere with host styles

### Usage:

```tsx
import { InteropWidget } from '@persistenceone/interop-widget';
import '@persistenceone/interop-widget/style.css';

<InteropWidget />
```

### Class Examples:

Instead of standard Tailwind classes, the widget uses prefixed classes:
- `mx-auto` → `iw-mx-auto`
- `flex` → `iw-flex`
- `p-4` → `iw-p-4`
- `text-center` → `iw-text-center`

## Default Route Configuration

You can pre-configure the widget with default source and destination chains and tokens:

```tsx
import { InteropWidget } from '@persistenceone/interop-widget';

const defaultRouteConfig = {
  fromChain: 'BNB Chain',
  fromToken: 'BTCB',
  toChain: 'Base',
  toToken: 'CBBTC'
};

<InteropWidget defaultRouteConfig={defaultRouteConfig} />
```

### Supported Chains and Tokens

The widget currently supports BSC and Base chains with their respective Bitcoin tokens. See the [Configuration Guide](#configuration) for the complete list.

## Advanced Components

### Tooltip Component

The widget includes a powerful tooltip component that renders outside parent containers to avoid overflow issues:

```tsx
import { Tooltip } from '@persistenceone/interop-widget';

<Tooltip content="This is a tooltip" direction="top">
  <button>Hover me</button>
</Tooltip>
```

**Features:**
- Multiple directions (top, bottom, left, right)
- Portal rendering (no overflow issues)
- Customizable delay
- Theme integration
- Click outside to close

### Modal Component

```tsx
import { Modal } from '@persistenceone/interop-widget';

<Modal isOpen={isModalOpen} onClose={() => setIsModalOpen(false)}>
  <h2>Modal Content</h2>
  <p>This is a modal dialog.</p>
</Modal>
```

### Toast Component

```tsx
import { Toast } from '@persistenceone/interop-widget';

<Toast 
  isOpen={showToast}
  onClose={() => setShowToast(false)}
  title="Success!"
  description="Transaction completed"
  status="success"
/>
```

## Theme Structure

The theme object has a simple structure:

```tsx
interface Theme {
  color: {
    'primary-bg': string;
    'secondary-bg': string;
    'ternary-bg': string;
    'text-primary': string;
    'text-secondary': string;
    'text-tertiary': string;
  };
}
```

## Default Theme

```tsx
const defaultTheme = {
  color: {
    'primary-bg': '#ffffff',
    'secondary-bg': '#f8f9fa',
    'ternary-bg': '#e9ecef',
    'text-primary': '#212529',
    'text-secondary': '#6c757d',
    'text-tertiary': '#adb5bd',
  },
};
```

## Examples

### Dark Theme
```tsx
const darkTheme = {
  color: {
    'primary-bg': '#1a1a1a',
    'secondary-bg': '#2d2d2d',
    'ternary-bg': '#404040',
    'text-primary': '#ffffff',
    'text-secondary': '#b3b3b3',
    'text-tertiary': '#808080',
  },
};

<InteropWidget theme={darkTheme} />
```

### Light Theme
```tsx
const lightTheme = {
  color: {
    'primary-bg': '#ffffff',
    'secondary-bg': '#f8f9fa',
    'ternary-bg': '#e9ecef',
    'text-primary': '#212529',
    'text-secondary': '#6c757d',
    'text-tertiary': '#adb5bd',
  },
};

<InteropWidget theme={lightTheme} />
```

### Partial Theme (Override Only What You Need)
```tsx
const partialTheme = {
  color: {
    'primary-bg': '#ff0000', // Only change primary background
  },
};

<InteropWidget theme={partialTheme} />
```

## Configuration

### Supported Chains

Currently, the widget supports the following chains:

#### Mainnet
- **Base** (Chain ID: 8453) - Base blockchain
- **BNB Chain** (Chain ID: 56) - Binance Smart Chain

#### Testnet
- **Sepolia Base** (Chain ID: 84532) - Base testnet
- **BEVM** (Chain ID: 11503) - BEVM testnet

### Supported Tokens

#### Mainnet Tokens
- **Base Chain**:
  - `CBBTC` - Core Bitcoin (Contract: 0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf)

- **BNB Chain**:
  - `BTCB` - Bitcoin BEP2 (Contract: 0x7130d2A12B9BCbFAe4f2634d864A1Ee1Ce3Ead9c)

#### Testnet Tokens
- **Sepolia Base**:
  - `CBBTC` - Core Bitcoin (Contract: 0xfaeec4E06C3D0439d2ac55473b4a45758031f86B)

- **BEVM**:
  - `WBTC` - Wrapped Bitcoin (Contract: 0xff204e2681a6fa0e2c3fade68a1b28fb90e4fc5f)

### Chain-Token Mapping

The widget enforces type-safe chain-token combinations:

```tsx
type ChainTokenMapping = {
  "Sepolia Base": "CBBTC";
  "BEVM": "WBTC";
  "Base": "CBBTC";
  "BNB Chain": "BTCB";
};
```

## API Reference

### InteropWidget Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `theme` | `Partial<Theme>` | `defaultTheme` | Custom theme object |
| `defaultRouteConfig` | `DefaultRouteConfig` | `undefined` | Pre-configured route |
| `network` | `'mainnet' \| 'testnet'` | `'mainnet'` | Network environment |

### DefaultRouteConfig

```tsx
interface DefaultRouteConfig {
  fromChain: ChainName;
  fromToken: TokenName;
  toChain: ChainName;
  toToken: TokenName;
}
```