feat: implement invoice co-creator real-time presence indicators

[Barbie-Dev]

Summary

Implement real-time presence indicators for invoice co-creators, enabling users to see who else is viewing/editing an invoice and which sections they're currently focused on.

Changes Made

New Files Created

1. src/types/presence.ts - Type definitions for presence system

   • InvoiceSectionFocus: Enum for tracking viewed sections (details, payments, recipients)
   • PresenceHeartbeat: Data sent to server on each heartbeat (user ID, name, focused section)
   • CoCreatorPresence: Complete presence state including timestamps and last seen data
   • PresenceRosterUpdate: Server response containing active user roster

2. src/hooks/useInvoicePresence.ts - Custom React hook for presence management

   • Sends heartbeat updates every 5 seconds to /api/presence/[invoiceId]
   • Fetches and maintains active co-creator roster
   • Tracks current user's focused invoice section
   • Implements exponential backoff for reconnection (up to 30 seconds)
   • Provides connection state and error handling
   • Automatically cleans up on component unmount

3. src/components/PresenceBar.tsx - UI component displaying active co-creators

   • Shows avatar pills for each active user in a horizontal row
   • Displays user name and focused section on hover
   • Handles overflow when 6+ users are present with "+N" indicator
   • Shows complete list of overflow users in tooltip
   • Color-coded section rings: blue (details), green (payments), purple (recipients)

4. src/components/InvoiceSection.tsx - Wrapper for automatic focus detection

   • Uses IntersectionObserver API for performant viewport tracking
   • Detects when sections enter/exit viewport (30% visibility threshold)
   • Triggers focus change callbacks automatically
   • No manual scroll listeners needed

5. src/app/api/presence/[invoiceId]/route.ts - Backend presence management

   • GET endpoint: Retrieve current active co-creator roster
   • POST endpoint: Accept heartbeat updates and return roster
   • In-memory presence store with automatic cleanup
   • Removes inactive users after 10 seconds of missed heartbeats
   • Permission validation (returns 403 for unauthorized access)
   • Real-time roster management with timestamps

Modified Files

• src/app/invoice/[id]/page.tsx
  • Added imports for presence hook, bar component, and section wrapper
  • Initialized useInvoicePresence hook with user identification
  • Added PresenceBar component to display active co-creators
  • Wrapped three main sections with InvoiceSection for focus tracking:
    • Details section (invoice info, status, deadline)
    • Payments section (payment table and payment forms)
    • Recipients section (recipient payout tracker)

Features Implemented

Real-Time Presence Tracking

• ✅ 5-second heartbeat polling to presence API
• ✅ Automatic cleanup of inactive users (10-second timeout)
• ✅ Section-aware presence (tracks which part user is viewing)
• ✅ Automatic reconnection with exponential backoff
• ✅ Error handling and graceful degradation

User Interface

• ✅ Avatar pills showing active co-creators
• ✅ Hover tooltips displaying user name and current section
• ✅ Overflow handling for 6+ concurrent users with "+N" indicator
• ✅ Color-coded section indicators for quick visual identification
• ✅ Responsive and accessible design

Section Focus Detection

• ✅ Automatic viewport tracking using IntersectionObserver
• ✅ 30% visibility threshold for section detection
• ✅ Supports three main sections: details, payments, recipients
• ✅ No manual scroll listener overhead
• ✅ Seamless, performant tracking

Technical Details

Architecture

• Polling vs WebSocket: HTTP polling chosen for simpler deployment and horizontal scaling
• IntersectionObserver: Browser-native API for performant focus detection
• In-memory store: Ready for production migration to Redis
• 5-second interval: Balances real-time updates with server load
• 10-second timeout: Quick cleanup without false positives

API Design

• Stateless endpoints for horizontal scalability
• Permission validation on presence API
• Returns complete roster with each update
• Automatic cleanup reduces server memory usage

React Best Practices

• Custom hook for clean presence logic separation
• Proper cleanup on component unmount
• No conditional hook calls (all at top level)
• TypeScript types for type safety

Testing

Manual Testing Scenarios

1. Single user: Presence bar doesn't show
2. Multiple users: Avatar pills display for each co-creator
3. Section focus: Hover tooltips show current section
4. Overflow: "+N" pill appears when 6+ users viewing
5. Disconnection: Automatic reconnection with backoff
6. Inactive timeout: User disappears from roster after 10s

Build Status

✅ TypeScript compilation successful
✅ ESLint validation passed
✅ Next.js build successful
✅ No runtime errors

Production Considerations

• In-memory presence store works for MVP/demo
• Migrate to Redis for production horizontal scaling
• Consider WebSocket support for lower latency (optional enhancement)
• Add monitoring for presence API performance
• Consider rate limiting on heartbeat endpoint

Closes #431

[vercel]

@Barbie-Dev is attempting to deploy a commit to the kingsman-99's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Barbie-Dev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits