feat(ui): add StreamChatConfiguration.maybeOf() method

This method allows for safe access to the `StreamChatConfigurationData` from a `BuildContext`, returning null if no ancestor `StreamChatConfiguration` is found. This is useful for async operations where the context might not be guaranteed to have a `StreamChatConfiguration` above it.

The `StreamChatConfiguration.of()` method has been updated to use `maybeOf()` internally and now provides more detailed error messages if a `StreamChatConfiguration` is not found.

Author: xsahil03x

packages/stream_chat_flutter/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Added `emojiCode` property to `StreamReactionIcon` to support custom emojis in reactions.
 - Updated default reaction builders with standard emoji codes. (`❤️`, `👍`, `👎`, `😂`, `😮`)
+- Added `StreamChatConfiguration.maybeOf()` method for safe context access in async operations.
 
 ## Upcoming
 

packages/stream_chat_flutter/lib/src/stream_chat_configuration.dart

@@ -21,18 +21,69 @@ class StreamChatConfiguration extends InheritedWidget {
   bool updateShouldNotify(StreamChatConfiguration oldWidget) =>
       data != oldWidget.data;
 
-  /// Use this method to get the current [StreamChatThemeData] instance
+  /// Finds the [StreamChatConfigurationData] from the closest
+  /// [StreamChatConfiguration] ancestor that encloses the given context.
+  ///
+  /// This will throw a [FlutterError] if no [StreamChatConfiguration] is found
+  /// in the widget tree above the given context.
+  ///
+  /// Typical usage:
+  ///
+  /// ```dart
+  /// final config = StreamChatConfiguration.of(context);
+  /// ```
+  ///
+  /// If you're calling this in the same `build()` method that creates the
+  /// `StreamChatConfiguration`, consider using a `Builder` or refactoring into
+  /// a separate widget to obtain a context below the [StreamChatConfiguration].
+  ///
+  /// If you want to return null instead of throwing, use [maybeOf].
   static StreamChatConfigurationData of(BuildContext context) {
-    final streamChatConfiguration =
-        context.dependOnInheritedWidgetOfExactType<StreamChatConfiguration>();
+    final result = maybeOf(context);
+    if (result != null) return result;
 
-    assert(
-      streamChatConfiguration != null,
-      '''
-You must have a StreamChatConfigurationProvider widget at the top of your widget tree''',
-    );
+    throw FlutterError.fromParts(<DiagnosticsNode>[
+      ErrorSummary(
+        'StreamChatConfiguration.of() called with a context that does not '
+        'contain a StreamChatConfiguration.',
+      ),
+      ErrorDescription(
+        'No StreamChatConfiguration ancestor could be found starting from the '
+        'context that was passed to StreamChatConfiguration.of(). This usually '
+        'happens when the context used comes from the widget that creates the '
+        'StreamChatConfiguration itself.',
+      ),
+      ErrorHint(
+        'To fix this, ensure that you are using a context that is a descendant '
+        'of the StreamChatConfiguration. You can use a Builder to get a new '
+        'context that is under the StreamChatConfiguration:\n\n'
+        '  Builder(\n'
+        '    builder: (context) {\n'
+        '      final config = StreamChatConfiguration.of(context);\n'
+        '      ...\n'
+        '    },\n'
+        '  )',
+      ),
+      ErrorHint(
+        'Alternatively, split your build method into smaller widgets so that '
+        'you get a new BuildContext that is below the StreamChatConfiguration '
+        'in the widget tree.',
+      ),
+      context.describeElement('The context used was'),
+    ]);
+  }
 
-    return streamChatConfiguration!.data;
+  /// Finds the [StreamChatConfigurationData] from the closest
+  /// [StreamChatConfiguration] ancestor that encloses the given context.
+  ///
+  /// Returns null if no such ancestor exists.
+  ///
+  /// See also:
+  ///  * [of], which throws if no [StreamChatConfiguration] is found.
+  static StreamChatConfigurationData? maybeOf(BuildContext context) {
+    final streamChatConfiguration =
+        context.dependOnInheritedWidgetOfExactType<StreamChatConfiguration>();
+    return streamChatConfiguration?.data;
   }
 }