feat(ui)!: Enhance onAttachmentTap with fallback to default behavior

This commit introduces a significant enhancement to the `onAttachmentTap` callback, allowing for more flexible and powerful customization of attachment interactions.

Key changes:
- The `onAttachmentTap` callback signature is updated to `FutureOr<bool> Function(BuildContext, Message, Attachment)`.
- The callback now returns a `FutureOr<bool>`. Returning `true` signifies that the tap has been handled by custom logic, preventing the default behavior. Returning `false` allows the default SDK behavior (e.g., opening image/video viewer, launching URLs) to execute.
- The `BuildContext` is now passed as the first parameter to the callback.
- The `onLinkTap` callback is now respected for URL attachments, providing more granular control over link handling.

This change enables developers to implement custom logic for specific attachment types while seamlessly falling back to the default SDK handling for all other types, reducing boilerplate and improving user experience.

Author: xsahil03x

migrations/v10-migration.md

@@ -8,6 +8,10 @@
 
 This guide includes breaking changes grouped by release phase:
 
+### 🚧 Upcoming Beta
+
+- [onAttachmentTap](#-onattachmenttap)
+
 ### 🚧 v10.0.0-beta.8
 
 - [customAttachmentPickerOptions](#-customattachmentpickeroptions)
@@ -38,6 +42,79 @@ This guide includes breaking changes grouped by release phase:
 
 ---
 
+## 🧪 Migration for Upcoming Beta
+
+### 🛠 onAttachmentTap
+
+#### Key Changes:
+
+- `onAttachmentTap` callback signature has changed to support custom attachment handling with automatic fallback to default behavior.
+- Callback now receives `BuildContext` as the first parameter.
+- Returns `FutureOr<bool>` to indicate whether the attachment was handled.
+- Returning `true` skips default behavior, `false` uses default handling (URLs, images, videos, giphys).
+
+#### Migration Steps:
+
+**Before:**
+```dart
+StreamMessageWidget(
+  message: message,
+  onAttachmentTap: (message, attachment) {
+    // Could only override - no way to fallback to default behavior
+    if (attachment.type == 'location') {
+      showLocationDialog(context, attachment);
+    }
+    // Other attachment types (images, videos, URLs) lost default behavior
+  },
+)
+```
+
+**After:**
+```dart
+StreamMessageWidget(
+  message: message,
+  onAttachmentTap: (context, message, attachment) async {
+    if (attachment.type == 'location') {
+      await showLocationDialog(context, attachment);
+      return true; // Handled by custom logic
+    }
+    return false; // Use default behavior for images, videos, URLs, etc.
+  },
+)
+```
+
+**Example: Handling multiple custom types**
+```dart
+StreamMessageWidget(
+  message: message,
+  onAttachmentTap: (context, message, attachment) async {
+    switch (attachment.type) {
+      case 'location':
+        await Navigator.push(
+          context,
+          MaterialPageRoute(builder: (_) => MapView(attachment)),
+        );
+        return true;
+      
+      case 'product':
+        await showProductDialog(context, attachment);
+        return true;
+      
+      default:
+        return false; // Images, videos, URLs use default viewer
+    }
+  },
+)
+```
+
+> ⚠️ **Important:**  
+> - The callback now requires `BuildContext` as the first parameter
+> - Must return `FutureOr<bool>` - `true` if handled, `false` for default behavior
+> - Default behavior automatically handles URL previews, images, videos, and giphys
+> - Supports both synchronous and asynchronous operations
+
+---
+
 ## 🧪 Migration for v10.0.0-beta.8
 
 ### 🛠 customAttachmentPickerOptions
@@ -750,6 +827,11 @@ StreamMessageWidget(
 
 ## 🎉 You're Ready to Migrate!
 
+### For Upcoming Beta:
+- ✅ Update `onAttachmentTap` callback signature to include `BuildContext` as first parameter
+- ✅ Return `FutureOr<bool>` from `onAttachmentTap` - `true` if handled, `false` for default behavior
+- ✅ Leverage automatic fallback to default handling for standard attachment types (images, videos, URLs)
+
 ### For v10.0.0-beta.8:
 - ✅ Replace `customAttachmentPickerOptions` with `attachmentPickerOptionsBuilder` to access and modify default options
 - ✅ Replace `onCustomAttachmentPickerResult` with `onAttachmentPickerResult` that returns `FutureOr<bool>`

packages/stream_chat_flutter/CHANGELOG.md

@@ -1,3 +1,36 @@
+## Upcoming Beta
+
+🛑️ Breaking
+
+- `onAttachmentTap` callback signature has changed to support custom attachment handling with automatic fallback to default behavior. The callback now receives `BuildContext` as the first parameter and returns `FutureOr<bool>` to indicate if the attachment was handled.
+  ```dart
+  // Before
+  StreamMessageWidget(
+    message: message,
+    onAttachmentTap: (message, attachment) {
+      // Could only override - no way to fallback to default behavior
+      if (attachment.type == 'location') {
+        showLocationDialog(context, attachment);
+      }
+      // Other attachment types lost default behavior
+    },
+  )
+  
+  // After
+  StreamMessageWidget(
+    message: message,
+    onAttachmentTap: (context, message, attachment) async {
+      if (attachment.type == 'location') {
+        await showLocationDialog(context, attachment);
+        return true; // Handled by custom logic
+      }
+      return false; // Use default behavior for images, videos, URLs, etc.
+    },
+  )
+  ```
+
+For more details, please refer to the [migration guide](../../migrations/v10-migration.md).
+
 ## 10.0.0-beta.8
 
 🛑️ Breaking
@@ -54,6 +87,8 @@
     },
   )
   ```
+  
+For more details, please refer to the [migration guide](../../migrations/v10-migration.md).
 
 - Included the changes from version [`9.19.0`](https://pub.dev/packages/stream_chat_flutter/changelog).
 

packages/stream_chat_flutter/lib/src/message_widget/message_card.dart

@@ -83,8 +83,8 @@ class MessageCard extends StatefulWidget {
   /// {@macro attachmentShape}
   final ShapeBorder? attachmentShape;
 
-  /// {@macro onAttachmentTap}
-  final StreamAttachmentWidgetTapCallback? onAttachmentTap;
+  /// {@macro onAttachmentWidgetTap}
+  final OnAttachmentWidgetTap? onAttachmentTap;
 
   /// {@macro onShowMessage}
   final ShowMessageCallback? onShowMessage;
@@ -188,6 +188,7 @@ class _MessageCardState extends State<MessageCard> {
             attachmentShape: widget.attachmentShape,
             onAttachmentTap: widget.onAttachmentTap,
             onShowMessage: widget.onShowMessage,
+            onLinkTap: widget.onLinkTap,
             onReplyTap: widget.onReplyTap,
             attachmentActionsModalBuilder: widget.attachmentActionsModalBuilder,
           ),

packages/stream_chat_flutter/lib/src/message_widget/message_widget.dart

@@ -377,8 +377,8 @@ class StreamMessageWidget extends StatefulWidget {
   /// {@macro onMessageActionTap}
   final OnMessageActionTap<CustomMessageAction>? onCustomActionTap;
 
-  /// {@macro onMessageWidgetAttachmentTap}
-  final StreamAttachmentWidgetTapCallback? onAttachmentTap;
+  /// {@macro onAttachmentWidgetTap}
+  final OnAttachmentWidgetTap? onAttachmentTap;
 
   /// {@macro attachmentActionsBuilder}
   final AttachmentActionsBuilder? attachmentActionsModalBuilder;
@@ -462,7 +462,7 @@ class StreamMessageWidget extends StatefulWidget {
     OnReactionsHover? onReactionsHover,
     List<StreamMessageAction>? customActions,
     OnMessageActionTap<CustomMessageAction>? onCustomActionTap,
-    void Function(Message message, Attachment attachment)? onAttachmentTap,
+    OnAttachmentWidgetTap? onAttachmentTap,
     Widget Function(BuildContext, User)? userAvatarBuilder,
     Size? imageAttachmentThumbnailSize,
     String? imageAttachmentThumbnailResizeType,

packages/stream_chat_flutter/lib/src/message_widget/message_widget_content.dart

@@ -152,8 +152,8 @@ class MessageWidgetContent extends StatelessWidget {
   /// {@macro attachmentShape}
   final ShapeBorder? attachmentShape;
 
-  /// {@macro onAttachmentTap}
-  final StreamAttachmentWidgetTapCallback? onAttachmentTap;
+  /// {@macro onAttachmentWidgetTap}
+  final OnAttachmentWidgetTap? onAttachmentTap;
 
   /// {@macro onShowMessage}
   final ShowMessageCallback? onShowMessage;