@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

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

Quick Start

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.

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.

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.

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

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

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

With IconView Integration

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

Custom Styling

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

React Integration

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

<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