feat: add user mention/tagging with @ symbol

[Copilot]

Description

Implements user mention/tagging functionality via @ symbol. When users type @ in the text field, a filtered list of participants appears; selecting one inserts @username at cursor position. Mentions render with distinct styling in messages.

Implementation

Configuration API (via TextFieldConfiguration):

• onMentionTriggered: Callback with search text when @ is typed
• mentionTriggerCharacter: Customizable trigger character (default @)
• mentionTextStyle: Styling for @mentions in rendered messages

Detection & Insertion:

• ChatUITextField detects @ and extracts partial name after trigger
• Triggers callback to filter users and populate suggestions
• insertMention() replaces partial text with full @username at cursor
• Clears suggestions on space or when @ is removed

Visual Rendering:

• TextMessageView parses @mentions via regex @\w+
• Renders mentions as RichText with bold/colored styling
• Default: yellow (outgoing), blue (incoming)

Reuses existing infrastructure:

• Leverages SuggestionList and SuggestionItemData for user selection
• Integrates with ChatController.newSuggestions

Example Usage

sendMessageConfig: SendMessageConfiguration(
  textFieldConfig: TextFieldConfiguration(
    onMentionTriggered: (searchText) {
      final users = chatController.otherUsers
          .where((u) => u.name.toLowerCase().contains(searchText.toLowerCase()))
          .toList();
      
      chatController.newSuggestions.value = users
          .map((u) => SuggestionItemData(text: u.name))
          .toList();
    },
    mentionTextStyle: const TextStyle(
      fontWeight: FontWeight.bold,
      color: Colors.blue,
    ),
  ),
),

replySuggestionsConfig: ReplySuggestionsConfig(
  onTap: (item) {
    final state = context.findAncestorStateOfType<SendMessageWidgetState>();
    state?.insertMention(item.text);
    chatController.removeReplySuggestions();
  },
),

Files Changed

Library (6): typedefs.dart, send_message_configuration.dart, chatui_textfield.dart, send_message_widget.dart, text_message_view.dart, message_view.dart

Example (2): main.dart, data.dart

Docs (2): README.md, documentation.md

Checklist

• The title of my PR starts with a Conventional Commit prefix (fix:, feat:, docs: etc).
• I have followed the Contributor Guide when preparing my PR.
• I have updated/added tests for ALL new/updated/fixed functionality.
• I have updated/added relevant documentation in docs and added dartdoc comments with ///.
• I have updated/added relevant examples in examples or docs.

Breaking Change?

• Yes, this PR is a breaking change.
• No, this PR is not a breaking change.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://storage.googleapis.com/flutter_infra_release/flutter/f6344b75dcf861d8bf1f1322780b8811f982e31a/dart-sdk-linux-x64.zip
  • Triggering command: /usr/bin/curl curl --retry 3 --continue-at - --location --output /tmp/flutter/bin/cache/dart-sdk-linux-x64.zip REDACTED (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add Tag User Functionality in Chat</issue_title>
<issue_description>Is your feature request related to a problem? Please describe.
Currently, users can communicate in the group chat, but there's no way to mention/tag specific users using @username. This makes it difficult to direct messages at particular participants, especially in larger group conversations

Describe the solution you'd like
I'd like to introduce user tagging via @ in the chat input, similar to how platforms like Slack or WhatsApp handle mentions. Here's what I envision:
When the user types @, a searchable list of group members should appear.
Selecting a user auto-completes the @username in the chat input.
When the message is sent, the mention is visually distinct (e.g. bold, colored).
The backend may optionally store tagged users (e.g. via user ID for notifications or metadata).
(Optional) Tagging a user could notify them directly via push/email.

Describe alternatives you've considered
Manual mentions: Users just type someone’s name manually, but this lacks structure, styling, and can't be tied to actual users for notifications.

Highlight keywords: Some chats use #hashtags or keywords, but this doesn’t help with user-specific tagging.

Additional context
The project is using the chatview package for the Flutter frontend.
Tagging should work with TextFieldConfiguration inside SendMessageConfiguration.
Ideal for teams, communities, or customer support scenarios.
Screenshots from Slack, Discord, or WhatsApp mentions can serve as UI inspiration.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add Tag User Functionality in Chat #378

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.