npm package: @lukso/up-connector
Description: Universal Profile connector with draggable avatar and connection modal
Author: LUKSO
Latest version: 0.10.15

# @lukso/up-connector

Universal Profile connector with draggable avatar and responsive connection modal.

## Features

- 🎯 **Draggable Avatar** - Floating avatar that snaps to corners and can be hidden at edges
- 📱 **Responsive Modal** - Mobile-first design that scales from overlay to full-screen
- ✨ **Smooth Animations** - Beautiful avatar-to-modal animations
- 🔗 **Connection Management** - Auto-connect, persistence, and state management
- 🎨 **IconView Integration** - Works with `@lukso/transaction-view-core` components
- 🌙 **Theme Support** - Light/dark themes with auto-detection

## Installation

```bash
npm install @lukso/up-connector
# or
pnpm add @lukso/up-connector
```

## Quick Start

```javascript
import { createConnector } from '@lukso/up-connector';

// Create connector instance
const connector = createConnector({
  avatar: {
    initialPosition: 'top-right',
    avatarSize: 60
  },
  modal: {
    theme: 'auto',
    closeOnBackdrop: true
  },
  autoConnect: true,
  onConnectionChange: (state, data) => {
    console.log('Connection state:', state, data);
  }
});
```

## API Reference

### UPConnector

Main class that orchestrates the avatar and modal components.

```typescript
interface ConnectorConfig {
  avatar?: AvatarOptions;
  modal?: ModalOptions;
  autoConnect?: boolean;
  persistConnection?: boolean;
  storageKey?: string;
  chainId?: number;
  rpcUrl?: string;
  onConnectionChange?: (state: ConnectionState, data?: any) => void;
}
```

#### Methods

- `connect(providerId?: string)` - Connect to wallet
- `disconnect()` - Disconnect wallet
- `showModal()` - Show connection/account modal
- `hideModal()` - Hide modal
- `isConnected()` - Check connection status
- `getConnectionState()` - Get current connection state
- `getConnectedAddress()` - Get connected wallet address
- `destroy()` - Clean up and remove components

### DraggableAvatar

Floating avatar component with drag-and-drop functionality.

```typescript
interface AvatarOptions {
  // IconView integration
  address?: string;
  resolved?: AddressData;
  size?: 'x-small' | 'small' | 'medium' | 'large';
  label?: string;

  // Fallback options
  fallbackColor?: string;
  fallbackText?: string;
  fallbackImage?: string;

  // Behavior
  avatarSize?: number;
  initialPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
  hideThreshold?: number;
  hideOffset?: number;

  // Callbacks
  onClick?: (event: MouseEvent, data: any) => void;
  onPositionChange?: (position: string) => void;
}
```

### ConnectorModal

Responsive modal dialog for wallet connection and account management.

```typescript
interface ModalOptions {
  theme?: 'light' | 'dark' | 'auto';
  borderRadius?: number;
  closeOnBackdrop?: boolean;
  closeOnEscape?: boolean;
  showCloseButton?: boolean;
  animationDuration?: number;

  // Animation from avatar
  animateFrom?: {
    x: number;
    y: number;
    width: number;
    height: number;
  };

  // Callbacks
  onConnect?: (result: { address: string; provider: any }) => void;
  onDisconnect?: () => void;
  onClose?: () => void;
}
```

## Usage Examples

### Basic Usage

```javascript
import { createConnector } from '@lukso/up-connector';

const connector = createConnector({
  onConnectionChange: (state, data) => {
    if (state === 'connected') {
      console.log('Connected to:', data.address);
    }
  }
});
```

### With IconView Integration

```javascript
const connector = createConnector({
  avatar: {
    address: '0x1234567890123456789012345678901234567890',
    size: 'large',
    avatarSize: 80,
    componentLoader: async () => {
      await import('@lukso/transaction-view-core/shared');
      return true;
    }
  }
});
```

### Custom Styling

```javascript
const connector = createConnector({
  avatar: {
    fallbackColor: 'linear-gradient(45deg, #ff6b6b, #4ecdc4)',
    fallbackText: '🚀',
    avatarSize: 70
  },
  modal: {
    theme: 'dark',
    borderRadius: 20,
    animationDuration: 400
  }
});
```

### React Integration

```jsx
import { createConnector } from '@lukso/up-connector';
import { useEffect, useState } from 'react';

function WalletConnector() {
  const [connector, setConnector] = useState(null);
  const [isConnected, setIsConnected] = useState(false);

  useEffect(() => {
    const conn = createConnector({
      onConnectionChange: (state) => {
        setIsConnected(state === 'connected');
      }
    });
    setConnector(conn);

    return () => conn.destroy();
  }, []);

  return (
    <div>
      <button onClick={() => connector?.showModal()}>
        {isConnected ? 'Account' : 'Connect'}
      </button>
    </div>
  );
}
```

### Vue Integration

```vue
<template>
  <button @click="showConnector">
    {{ isConnected ? 'Account' : 'Connect' }}
  </button>
</template>

<script setup>
import { createConnector } from '@lukso/up-connector';
import { onMounted, onUnmounted, ref } from 'vue';

const isConnected = ref(false);
let connector = null;

onMounted(() => {
  connector = createConnector({
    onConnectionChange: (state) => {
      isConnected.value = state === 'connected';
    }
  });
});

onUnmounted(() => {
  connector?.destroy();
});

const showConnector = () => {
  connector?.showModal();
};
</script>
```

## Mobile Design

The modal automatically adapts to different screen sizes:

- **Desktop** (>640px): Centered overlay modal
- **Mobile** (≤640px): Bottom sheet that slides up
- **Small screens** (≤480px): Full-screen takeover

The avatar remains draggable and functional on all screen sizes with proper touch event handling.

## Animation System

The connector features a sophisticated animation system:

1. **Avatar-to-Modal**: Modal expands from the avatar's position
2. **Scale Animation**: Avatar scales during drag operations
3. **Smooth Transitions**: All state changes are smoothly animated
4. **Mobile Optimized**: Touch-friendly animations

## Debug Logs

At runtime we look at the Local Storage `debug` key to show various logs. The following log streams are
available:

- `connect-modal:info` -> Show info logs for connect modal

## Browser Support

- Chrome/Edge 88+
- Firefox 85+
- Safari 14+
- Mobile browsers with modern JavaScript support

## License

MIT