Contact Management

​

Overview

​

Key Features

​

Contact Directory

• Contact Cards - Individual cards for each contact
• Favorite Filtering - Show only favorited contacts
• Quick Actions - Edit, favorite/unfavorite, delete
• Empty State - Helpful message when no contacts exist

​

Contact Information

• Name - Contact’s full name
• Wallet Address - Blockchain wallet address (Berachain format)
• Email - Email address
• Phone - Phone number
• Notes - Free-form notes field
• Favorite Status - Boolean flag for quick filtering

​

Adding Contacts

​

Add Contact Flow

1. Click “Add Contact” button
2. AddContactModal opens
3. Enter contact information:
   • Name (required)
   • Wallet address (optional)
   • Email (optional)
   • Phone (optional)
   • Notes (optional)
4. Click “Save”
5. Contact is created and appears in directory

​

Add Contact Modal

• Form Fields - Input for all contact properties
• Validation - Required field checks (name)
• Error Display - Shows addContactError from context
• Save Button - Calls handleAddContact(contact)
• Cancel Button - Closes modal without saving

​

Managing Contacts

​

Contact Card

• Avatar - Fallback with initials
• Name - Primary identifier
• Contact Info - Wallet, email, phone (if provided)
• Notes Preview - Truncated notes field
• Favorite Icon - Star/outline star for toggle
• Actions Menu - Edit and delete options

​

Editing Contacts

1. Click edit action in contact card
2. Update contact fields
3. Call updateContact(contact) from context
4. Contact updates in directory

​

Favoriting Contacts

const handleToggleIsFavorite = async (c: Contact) => {
  c.is_favorite = !c.is_favorite
  await updateContact(c)
}

​

Deleting Contacts

1. Click delete action in contact card
2. DeleteContactModal opens with confirmation
3. User confirms deletion
4. handleDeleteContact(id) is called
5. Contact is removed from directory

​

Filtering

​

Favorites Filter

<Checkbox
  id="only-favorites"
  checked={onlyFavorites}
  onCheckedChange={() => setOnlyFavorites(!onlyFavorites)}
/>
<Label htmlFor="only-favorites">
  Filter by favorites
</Label>

​

Filter Logic

contacts.map((contact, index) => {
  if(onlyFavorites && !contact.is_favorite) return
  return <ContactCard key={contact.id} contact={contact} ... />
})

​

State Management

​

Context Provider

const {
  contacts,              // Array of Contact objects
  contactsStatus,        // "loading" | "loaded" | "error"
  addContact,            // (contact: Contact) => Promise<void>
  updateContact,         // (contact: Contact) => Promise<void>
  getContacts,           // () => Promise<void>
  deleteContact          // (id: number) => Promise<void>
} = useContacts()

​

App Context

const {
  status,     // Auth status
  error,      // Global error state
  setError    // Set error message
} = useApp()

​

Local State

const [addContactModalOpen, setAddContactModalOpen] = useState(false)
const [deleteContactModalOpen, setDeleteContactModalOpen] = useState(false)
const [deleteContactModalContact, setDeleteContactModalContact] = useState<Contact>()
const [onlyFavorites, setOnlyFavorites] = useState(false)

​

Authentication

​

Auth Guard

useEffect(() => {
  if(status === "unauthenticated") {
    router.replace("/")
  }
}, [status])

​

Loading State

if (status === "loading") {
  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="animate-spin rounded-full h-12 w-12 border-t-2 border-b-2 border-[#eb6c6c]"></div>
    </div>
  )
}

​

UI Components

​

Page Layout

• Header - “Contacts” title and description
• Filter Checkbox - Favorites filter control
• Contact List - Grid/list of contact cards
• Add Button - Primary action button
• Count Display - Shows filtered contact count

​

Modals

• AddContactModal - Create new contact
• DeleteContactModal - Confirm deletion
• EditContactModal - Edit existing contact (inline in ContactCard)

​

ContactCard Component

interface ContactCardProps {
  contact: Contact
  handleToggleIsFavorite: (c: Contact) => void
  updateContact: (c: Contact) => void
  toggleDeleteContactModal: () => void
  setDeleteContactModalContact: (c: Contact) => void
}

​

Error Handling

​

Error Display

<AddContactModal
  open={addContactModalOpen}
  onOpenChange={toggleAddContactModal}
  handleAddContact={addContact}
  addContactError={error}  // Displays error in modal
/>

​

Error Clearing

const toggleAddContactModal = () => {
  setError(null)  // Clear error when opening modal
  setAddContactModalOpen(!addContactModalOpen)
}

​

Contact Count

<div className="text-sm text-gray-500 dark:text-gray-400">
  Showing {contacts.length} {!onlyFavorites ? "" : "favorite"} contact
  {(contacts.filter((contact) => contact.is_favorite === true || !onlyFavorites)).length !== 1 ? "s" : ""}
</div>

​

API Integration

// Get all contacts
GET /contacts

// Create contact
POST /contacts
Body: { name, wallet_address?, email?, phone?, notes?, is_favorite }

// Update contact
PUT /contacts/:id
Body: Contact

// Delete contact
DELETE /contacts/:id

​

Contact Type

interface Contact {
  id: number
  user_id?: string
  name: string
  wallet_address?: string
  email?: string
  phone?: string
  notes?: string
  is_favorite: boolean
  created_at?: string
  updated_at?: string
}

​

Best Practices

​

Data Management

1. Validate Wallet Addresses - Ensure proper Berachain address format
2. Email Validation - Check email format before saving
3. Duplicate Prevention - Warn if contact with same wallet/email exists
4. Data Persistence - Ensure changes are saved to backend

​

User Experience

1. Clear Empty State - Show helpful message when no contacts
2. Favorite Quick Access - Make favoriting intuitive and visible
3. Bulk Actions - Consider adding bulk edit/delete for power users
4. Search - Add search functionality for large contact lists
5. Import/Export - Allow CSV import/export for backup

​

Performance

1. Pagination - Implement for >100 contacts
2. Virtual Scrolling - For very large lists
3. Debounced Search - If search is added
4. Optimistic Updates - Update UI before backend confirms

​

Wallet Integration

​

Wallet Address Field

• Store Berachain wallet addresses
• Link to wallet balance/transaction views
• Enable quick transfers to contact
• Verify address ownership (future enhancement)

​

Quick Send Integration

<Button onClick={() => sendToContact(contact.wallet_address)}>
  Send SFLUV
</Button>

​

Accessibility

​

Keyboard Navigation

• Tab through contact cards
• Enter to open actions menu
• Arrow keys to navigate within menu
• Escape to close modals

​

Screen Reader Support

• Label all form fields
• Announce contact count changes
• Describe favorite status
• Provide context for actions

​

Focus Management

• Return focus to trigger after modal close
• Focus first field when modal opens
• Trap focus within modal

​

Troubleshooting

​

Common Issues

• Check contactsStatus in context
• Verify authentication status
• Check network requests in dev tools
• Confirm backend endpoint is reachable

• Verify updateContact() completes
• Check for error messages
• Confirm optimistic update vs backend response
• Check network tab for failed requests

• Verify is_favorite property on contacts
• Check filter logic in map function
• Ensure state updates trigger re-render

​

Debugging Tips

// Log contacts array
console.log("Contacts:", contacts)

// Check favorite filter state
console.log("Only favorites:", onlyFavorites)

// Verify contact update
console.log("Updated contact:", contact)

// Check context status
console.log("Contacts status:", contactsStatus)

​

Future Enhancements

​

Planned Features

1. Contact Groups - Organize contacts into categories
2. Tags - Multi-tag support for flexible filtering
3. Contact Sharing - Share contacts with other users
4. QR Code - Generate QR code for contact info
5. vCard Export - Export as standard vCard format
6. Contact Verification - Verify wallet ownership
7. Activity History - Track interactions with contact
8. Notes Timeline - Date-stamped notes entries

​

Integration Opportunities

1. Transaction History - Link to past transactions with contact
2. Workflow Collaboration - Add contacts as workflow participants
3. Messaging - Direct messaging to contacts
4. Calendar Integration - Schedule meetings with contacts
5. Profile Linking - Link to contact’s public profile