feat(TalkerWrapper): Enhance UI Feedback, Support Warning/Info messages

[huanguan1978]

feat(TalkerWrapper): Enhance Logging and UI Feedback Mechanism, Support Warning/Info messages.

// Existing error handling
void _handleError() {
  try {
    throw ArgumentError('-6 is not positive number');
  } catch (e, st) {
    talker.handle(e, st, 'Something wrong in calculation');
  }
}

// Existing exception handling
void _handleException() {
  try {
    throw Exception('Test service exception');
  } catch (e, st) {
    talker.handle(e, st);
  }
}

// New proposed log handling for UI feedback
// Can pass custom `message`, `title`, `logLevel` via TalkerLog.
void _handleLog() {
  final talkerLog = TalkerLog('Test log message', logLevel: TalkerLogLevel.warning); // Example with warning level
  talker.handle(talkerLog);
}

Summary by Sourcery

Extend TalkerWrapper and core logging to surface generic TalkerLog messages in the UI and treat them consistently in the error handling pipeline.

New Features:

• Add support in TalkerWrapper for displaying TalkerLog messages via snackbars with customizable titles and builders.
• Expose a new example button and handler to demonstrate TalkerLog-based UI feedback in the Flutter example app.

Enhancements:

• Allow TalkerErrorHandler to pass through TalkerLog instances without wrapping them as errors or exceptions.
• Default Talker.handle processing of TalkerLog to use an explicit log level, falling back to info when none is provided.

[sourcery-ai]

Reviewer's Guide

Adds support in TalkerWrapper for displaying UI alerts for generic TalkerLog messages (including warning/info levels), wires TalkerLog through the error handler pipeline, and updates examples to demonstrate the new behavior and default log level handling.

Sequence diagram for TalkerLog handling and UI alert display

sequenceDiagram
  actor User
  participant Button_HandleLog as Button_HandleLog
  participant Talker as Talker
  participant TalkerErrorHandler as TalkerErrorHandler
  participant TalkerWrapper as TalkerWrapper
  participant SnackbarContent as SnackbarContent
  participant UI as UI

  User->>Button_HandleLog: onPressed()
  activate Button_HandleLog
  Button_HandleLog->>Talker: handle(TalkerLog log)
  deactivate Button_HandleLog

  activate Talker
  Talker->>TalkerErrorHandler: handle(log, null)
  activate TalkerErrorHandler
  TalkerErrorHandler-->>Talker: TalkerLog(log)
  deactivate TalkerErrorHandler

  Talker->>Talker: _handleLogData(log, logLevel)
  Note right of Talker: logLevel = log.logLevel or LogLevel.info
  Talker-->>TalkerWrapper: stream emits TalkerLog
  deactivate Talker

  activate TalkerWrapper
  TalkerWrapper->>TalkerWrapper: if data is TalkerLog and options.enableLogAlerts
  TalkerWrapper->>SnackbarContent: create(message, title)
  activate SnackbarContent
  SnackbarContent-->>TalkerWrapper: instance
  deactivate SnackbarContent

  TalkerWrapper->>UI: showAlert(SnackbarContent)
  deactivate TalkerWrapper

  UI-->>User: Log snackbar visible

Loading

Class diagram for updated TalkerWrapperOptions and Talker log handling

classDiagram
  class Talker {
    +void handle(Object error, StackTrace? stack, String? message)
    -void _handleLogData(TalkerLog data, LogLevel logLevel)
  }

  class TalkerErrorHandler {
    +TalkerData? handle(Object exception, StackTrace? stack)
  }

  class TalkerWrapperOptions {
    <<immutable>>
    +String exceptionTitle = Error occurred
    +String errorTitle = Error occurred
    +String logTitle = Log message
    +TalkerExceptionBuilder? exceptionAlertBuilder
    +TalkerErrorBuilder? errorAlertBuilder
    +TalkerDataBuilder? logAlertBuilder
    +bool enableErrorAlerts = false
    +bool enableExceptionAlerts = true
    +bool enableLogAlerts = true
  }

  class TalkerWrapper {
    +TalkerWrapper(Talker talker, TalkerWrapperOptions options, Widget child)
    +Widget build(BuildContext context)
    -String _mapErrorMessage(String message)
  }

  class TalkerLog {
    +String message
    +String? title
    +TalkerLogLevel? logLevel
    +String get displayMessage()
  }

  class SnackbarContent {
    +String message
    +String title
  }

  class TalkerException {
  }

  class TalkerData {
  }

  class LogLevel {
    <<enum>>
    +info
    +warning
    +error
  }

  class TalkerLogLevel {
    <<enum>>
    +info
    +warning
    +error
  }

  Talker ..> TalkerLog : uses
  Talker ..> LogLevel : uses
  TalkerErrorHandler ..> TalkerLog : returns
  TalkerErrorHandler ..> TalkerException : returns
  TalkerErrorHandler ..> TalkerData : returns

  TalkerWrapper ..> Talker : observes data from
  TalkerWrapper ..> TalkerWrapperOptions : configures
  TalkerWrapper ..> SnackbarContent : creates
  TalkerWrapper ..> TalkerLog : handles

  TalkerLog --> TalkerData : extends

Loading

File-Level Changes

Change	Details	Files
Extend TalkerWrapperOptions and TalkerWrapper to support UI alerts for generic log messages.	Add configurable title, builder, and enable flag for log alerts to the options model Wire TalkerLog handling into TalkerWrapper listener to show a snackbar using either a custom builder or a default SnackbarContent Ensure early return after handling errors to avoid fall-through when displaying alerts	packages/talker_flutter/lib/src/ui/talker_wrapper/talker_wrapper_options.dart packages/talker_flutter/lib/src/ui/talker_wrapper/talker_wrapper.dart
Update Talker error handling to treat TalkerLog as pass-through data and ensure logs have a default log level.	Allow TalkerErrorHandler to return TalkerLog instances directly without re-wrapping them Adjust Talker._handle to pass an explicit default log level (info) when handling TalkerLog data	packages/talker/lib/src/utils/error_handler.dart packages/talker/lib/src/talker.dart
Enhance example apps to demonstrate new log handling and TalkerWrapper usage.	Add a new button and handler in the TalkerWrapper example to trigger a TalkerLog and show the corresponding UI alert Import the TalkerWrapper example in the main example file and document how to switch the root widget for testing	packages/talker_flutter/example/lib/talker_wrapper_example/talker_wrapper_example.dart packages/talker_flutter/example/lib/main.dart

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The doc comment for enableLogAlerts still says "will show exceptions message"; update it to reflect that it controls log messages instead to avoid confusion.
• Treating TalkerLog as a passthrough case in TalkerErrorHandler.report alongside TalkerException may be confusing semantically; consider either a dedicated branch/handler for logs or clarifying the naming to distinguish logs from exceptions.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The doc comment for `enableLogAlerts` still says "will show exceptions message"; update it to reflect that it controls log messages instead to avoid confusion.
- Treating `TalkerLog` as a passthrough case in `TalkerErrorHandler.report` alongside `TalkerException` may be confusing semantically; consider either a dedicated branch/handler for logs or clarifying the naming to distinguish logs from exceptions.

## Individual Comments

### Comment 1
<location> `packages/talker_flutter/lib/src/ui/talker_wrapper/talker_wrapper_options.dart:41-42` </location>
<code_context>
   /// [TalkerWrapper] will show error message if field is [true]
   final bool enableErrorAlerts;

   /// [TalkerWrapper] will show exceptions message if field is [true]
   final bool enableExceptionAlerts;
+
+  /// [TalkerWrapper] will show exceptions message if field is [true]
+  final bool enableLogAlerts;
 }
</code_context>

<issue_to_address>
**suggestion:** The doc comment for `enableLogAlerts` appears to be copy-pasted from the exception flag and is misleading.

This field controls log alerts, but its doc still refers to exceptions. Please update the wording to describe log messages/log alerts so it matches the actual behavior.

```suggestion
  /// [TalkerWrapper] will show log messages if field is [true]
  final bool enableLogAlerts;
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.01%. Comparing base (1ed15ab) to head (bf0cef8).
⚠️ Report is 176 commits behind head on master.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #466      +/-   ##
==========================================
- Coverage   98.63%   91.01%   -7.62%     
==========================================
  Files           3       13      +10     
  Lines         146      267     +121     
==========================================
+ Hits          144      243      +99     
- Misses          2       24      +22     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.