DialogUtils & Notifications

Relevant source files

The following files were used as context for generating this wiki page:

• routing_plan.md
• CLAUDE.md
• README.md
• authplan.md
• pubspec.yaml

Introduction

The DialogUtils & Notifications system within MoodTune serves as a centralized utility layer for managing user interactions that occur outside the standard page flow. This includes modal dialogs, bottom sheets, and transient notifications like snackbars. The system is designed to provide consistent styling and behavior across the application, ensuring that feedback—whether it be a success message after a mood analysis or an error during authentication—is delivered uniformly to the user.

This module works closely with the Routing System to manage transient UI states and the Authentication System to communicate session status and errors. By abstracting these UI patterns into DialogUtils, the project maintains a clean separation between business logic in BLoCs and presentation-specific feedback mechanisms.

Sources: routing_plan.md:112-115, CLAUDE.md:79-84

DialogUtils Architecture

The DialogUtils class is implemented as a utility with a private constructor to prevent instantiation, offering static methods for common UI interactions. It is located at lib/core/routing/dialog_utils.dart. This architecture ensures that any part of the application can trigger a dialog or notification without needing to manage the complex boilerplate of Flutter's showDialog or ScaffoldMessenger directly.

Core UI Components

The utility categorizes interactions into four primary types:

Component Type	Purpose	Common Use Cases
Confirmation Dialogs	Requires explicit user choice (Yes/No).	Deleting history, confirming audio upload.
Info Dialogs	Displays important information or alerts.	Feature explanations, non-critical errors.
Bottom Sheets	Contextual menus or complex inputs.	Catalog track confirmation, consent modals.
Snackbars	Transient, non-blocking feedback.	Success notifications, network errors, auth failures.

Sources: routing_plan.md:117-128, README.md:23-35

Interaction Flow

The following sequence diagram illustrates how a Presentation layer component (like a Page or BLoC listener) utilizes DialogUtils to provide feedback:

Notifications & Feedback

Notifications in MoodTune are primarily handled via Snackbars, which are styled to match the shadcn_ui theme, specifically utilizing the ShadSlateColorScheme. The system distinguishes between different types of feedback to help users quickly identify the nature of the message.

Feedback Categories

• Success: Used for positive outcomes, such as a successful mood analysis or account creation.
• Error: Integrated with the application's Failure classes (e.g., AuthFailure, NetworkFailure). These typically display the failure.message.
• Info: General updates that do not require action.

Sources: routing_plan.md:126-128, CLAUDE.md:48-51, authplan.md:137-142

Integration with State Management

In the Clean Architecture pattern used by MoodTune, BLoCs emit states containing error messages. The UI layer listens for these changes and uses DialogUtils to display the appropriate notification.

// Example BLoC consumption in lib/features/analysis/presentation/bloc/analysis_bloc.dart
result.fold(
  (failure) {
    // UI would then call:
    DialogUtils.showError(context, failure.message);
    emit(state.copyWith(status: AnalysisStatus.error, error: failure.message));
  },
  (analysis) => emit(state.copyWith(status: AnalysisStatus.success, currentAnalysis: analysis)),
);

Sources: CLAUDE.md:46-51, authplan.md:150-155

Component Specifications

Dialog Methods

The system provides standardized signatures for various interaction types:

• showConfirmDialog: Returns a Future<bool>, allowing the caller to await user confirmation.
• showAppBottomSheet<T>: Returns a generic type T?, useful for returning selected values from a list or modal.
• showSnackBar: The base method for transient alerts, typically wrapped by showError and showSuccess.

Sources: routing_plan.md:132-140

Dependency and Styling

The system relies on several external packages for its UI presentation, as defined in pubspec.yaml:

• shadcn_ui: Provides the primary component library for buttons and cards used within dialogs.
• flutter_bloc: Used to trigger dialogs based on state changes.
• cupertino_icons: Used for iconography within alerts and notifications.

Sources: pubspec.yaml:15-30, CLAUDE.md:92-95

Summary

The DialogUtils & Notifications system provides a robust, centralized mechanism for handling asynchronous user feedback and modal interactions in MoodTune. By standardizing these interactions, the application ensures that users receive consistent visual cues, whether they are uploading an MP3 for mood analysis or navigating the Jamendo catalog. The utility's integration with the project's Clean Architecture ensures that error handling from the Data and Domain layers is gracefully presented to the user through the Presentation layer.