feat: Add @mention support in comments and descriptions with email notifications

[owaisrizvi97]

Summary

Adds user @mention functionality to card comments and descriptions with automatic email notifications. Users can now tag teammates using @ autocomplete in both comment threads and card descriptions, triggering instant email notifications to mentioned members.

Features

Frontend

• @mention Autocomplete: Type @ in comments or descriptions to see workspace member suggestions
• Mention Chips: Mentioned users appear as blue-highlighted chips in the editor
• Shared Components: Extracted reusable MentionSuggestion module for consistent mention UI
• Lightweight CommentEditor: Purpose-built TipTap editor for comments with minimal extensions (no slash commands, YouTube embeds, or markdown)
• Performance Optimized: Uses ContentEditable for display mode to avoid initializing TipTap instances for every comment

Backend

• Email Notifications: Mentioned users receive immediate email notifications with:
  • Card title and workspace context
  • Comment preview (plain text, 200 char limit)
  • Direct link to the card
  • Respects white-label settings
• Fire-and-forget Pattern: Email sending never blocks comment creation
• Smart Filtering: Self-mentions don't trigger notifications
• HTML Parsing: Regex-based extraction of mentions from TipTap HTML output
• Repository Functions: New queries for fetching member emails and card notification context

Email Template

• React Email component following existing template patterns
• Preview text: "{name} mentioned you in {cardTitle}"
• Styled quote block for comment preview
• Blue "View Card" CTA button

Architecture Decisions

1. Email-Only Approach: No database table for notifications - keeps implementation simple and avoids migration complexity
2. TipTap Reuse: Leverages existing Mention extension instead of building custom autocomplete
3. Shared Modules: Extracted mention UI components from Editor.tsx to eliminate code duplication
4. Fire-and-forget: Email failures logged but never prevent comment creation
5. HTML as Source of Truth: Mentions embedded as <span data-type="mention" data-id="..."> elements

Files Changed

New Files

• apps/web/src/components/MentionSuggestion.tsx - Shared mention UI components
• apps/web/src/components/CommentEditor.tsx - Lightweight TipTap editor for comments
• packages/api/src/utils/mentions.ts - Mention parsing and email dispatch utilities
• packages/email/src/templates/mention-notification.tsx - Email template
• apps/web/src/utils/mentions.test.ts - Unit tests for mention parsing
• docs/feature-mention-notifications.md - Feature documentation

Modified Files

• apps/web/src/components/Editor.tsx - Now imports from shared MentionSuggestion module
• apps/web/src/views/card/components/Comment.tsx - Uses CommentEditor for editing, TipTap Editor for display
• apps/web/src/views/card/components/NewCommentForm.tsx - Replaced react-contenteditable with CommentEditor
• apps/web/src/views/card/index.tsx - Passes workspace members to comment components
• packages/api/src/routers/card.ts - Triggers mention emails in create/update operations
• packages/email/src/sendEmail.tsx - Registered MENTION_NOTIFICATION template
• packages/db/src/repository/card.repo.ts - Added getCardNotificationContext query
• packages/db/src/repository/workspace.repo.ts - Added getMembersWithEmailsByPublicIds query

Backward Compatibility

• ✅ No database schema changes
• ✅ Existing plain-text comments render correctly
• ✅ Email notifications are optional (controlled by NEXT_PUBLIC_DISABLE_EMAIL)
• ✅ Graceful degradation if SMTP not configured
• ✅ Respects existing workspace and email privacy settings

Testing

Automated

• Unit tests for mention HTML parsing (mentions.test.ts)
• Covers single mentions, multiple mentions, deduplication, and edge cases

Manual Testing Checklist

• Type @ in comment → suggestion popup appears
• Select member → mention chip renders with blue styling
• Submit comment → mention displays in activity list
• Mentioned user receives email with correct details
• Self-mentions don't trigger emails
• NEXT_PUBLIC_DISABLE_EMAIL=true → no emails sent
• Old comments without mentions still render correctly
• Edit comment with mentions → mentions preserved
• Multiple mentions in one comment → one email per user

Environment Variables

No new environment variables required. Uses existing SMTP configuration:

• SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD
• EMAIL_FROM
• NEXT_PUBLIC_DISABLE_EMAIL (optional - disables all emails)
• NEXT_PUBLIC_BASE_URL (required for card URLs in emails)

Performance Impact

• Minimal: Only adds TipTap editor to comment input (not display)
• Optimized Display: Uses ContentEditable with disabled={true} for rendered comments instead of full TipTap instances
• Async Email: Fire-and-forget pattern ensures zero latency impact on comment creation

Security

• ✅ Validates workspace membership before sending emails
• ✅ HTML content sanitized by TipTap
• ✅ Only mentions active workspace members with valid emails
• ✅ Respects existing permission system

Documentation

See docs/feature-mention-notifications.md for:

• Detailed implementation overview
• Architecture decision records
• File-by-file change summary
• Testing guidelines
• Deployment notes

[owaisrizvi97]

@hjball required your review please. This is extremely important functionality needed atm for our organization

[hjball]

What features/functionality are not covered by my PR? @owaisrizvi97