feat(notifications): add capability to dismiss a notification using NotificationDismisser or NotificationManager

Author: rafaeltonholo

feature/notification/api/src/commonMain/kotlin/net/thunderbird/feature/notification/api/NotificationManager.kt

@@ -0,0 +1,12 @@
+package net.thunderbird.feature.notification.api
+
+import net.thunderbird.feature.notification.api.dismisser.NotificationDismisser
+import net.thunderbird.feature.notification.api.sender.NotificationSender
+
+/**
+ * Manages sending and dismissing notifications.
+ *
+ * This interface combines the functionalities of [NotificationSender] and [NotificationDismisser]
+ * to provide a unified API for notification management.
+ */
+interface NotificationManager : NotificationSender, NotificationDismisser

feature/notification/api/src/commonMain/kotlin/net/thunderbird/feature/notification/api/NotificationRegistry.kt

@@ -58,4 +58,20 @@ interface NotificationRegistry {
      * @param notification The [Notification] object to unregister.
      */
     fun unregister(notification: Notification)
+
+    /**
+     * Checks if a specific notification is currently registered.
+     *
+     * @param notification The [Notification] object to check.
+     * @return `true` if the notification is registered, `false` otherwise.
+     */
+    operator fun contains(notification: Notification): Boolean
+
+    /**
+     * Checks if a notification with the given [notificationId] is currently registered.
+     *
+     * @param notificationId The ID of the notification to check.
+     * @return `true` if the notification is registered, `false` otherwise.
+     */
+    operator fun contains(notificationId: NotificationId): Boolean
 }

feature/notification/api/src/commonMain/kotlin/net/thunderbird/feature/notification/api/command/NotificationCommand.kt

@@ -47,7 +47,7 @@ abstract class NotificationCommand<TNotification : Notification>(
      * @property throwable The exception that caused the failure.
      */
     data class Failure<out TNotification : Notification>(
-        val command: NotificationCommand<out TNotification>,
+        val command: NotificationCommand<out TNotification>?,
         val throwable: Throwable,
     ) : CommandOutcome
 }

feature/notification/api/src/commonMain/kotlin/net/thunderbird/feature/notification/api/dismisser/NotificationDismisser.kt

@@ -0,0 +1,32 @@
+package net.thunderbird.feature.notification.api.dismisser
+
+import kotlinx.coroutines.flow.Flow
+import net.thunderbird.core.outcome.Outcome
+import net.thunderbird.feature.notification.api.NotificationId
+import net.thunderbird.feature.notification.api.command.NotificationCommand.Failure
+import net.thunderbird.feature.notification.api.command.NotificationCommand.Success
+import net.thunderbird.feature.notification.api.content.Notification
+
+/**
+ * Responsible for dismissing notifications by creating and executing the appropriate commands.
+ */
+interface NotificationDismisser {
+    /**
+     * Dismisses a notification with the given ID.
+     *
+     * @param id The ID of the notification to dismiss.
+     * @return A [Flow] of [Outcome] that emits either a [Success] with the dismissed [Notification]
+     * or a [Failure] with the [Notification] that failed to be dismissed.
+     */
+    fun dismiss(id: NotificationId): Flow<Outcome<Success<Notification>, Failure<Notification>>>
+
+    /**
+     * Dismisses a notification.
+     *
+     * @param notification The notification to dismiss.
+     * @return A [Flow] of [Outcome] that emits the result of the dismiss operation.
+     * The [Outcome] will be a [Success] containing the dismissed [Notification] if the operation was successful,
+     * or a [Failure] containing the [Notification] if the operation failed.
+     */
+    fun dismiss(notification: Notification): Flow<Outcome<Success<Notification>, Failure<Notification>>>
+}

feature/notification/api/src/commonMain/kotlin/net/thunderbird/feature/notification/api/dismisser/compat/NotificationDismisserCompat.kt

@@ -0,0 +1,50 @@
+package net.thunderbird.feature.notification.api.dismisser.compat
+
+import androidx.annotation.Discouraged
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.DisposableHandle
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.launchIn
+import kotlinx.coroutines.flow.onEach
+import net.thunderbird.core.outcome.Outcome
+import net.thunderbird.feature.notification.api.command.NotificationCommand.Failure
+import net.thunderbird.feature.notification.api.command.NotificationCommand.Success
+import net.thunderbird.feature.notification.api.content.Notification
+import net.thunderbird.feature.notification.api.dismisser.NotificationDismisser
+
+/**
+ * A compatibility layer for dismissing notifications from Java code.
+ *
+ * This class wraps [NotificationDismisser] and provides a Java-friendly API for sending notifications
+ * and receiving results via a callback interface.
+ *
+ * It is marked as [Discouraged] because it is intended only for use within Java classes.
+ * Kotlin code should use [NotificationDismisser] directly.
+ *
+ * @property notificationDismisser The underlying [NotificationDismisser] instance.
+ * @property mainImmediateDispatcher The [CoroutineDispatcher] used for launching coroutines.
+ */
+@Discouraged("Only for usage within a Java class. Use NotificationDismisser instead.")
+class NotificationDismisserCompat @JvmOverloads constructor(
+    private val notificationDismisser: NotificationDismisser,
+    mainImmediateDispatcher: CoroutineDispatcher = Dispatchers.Main.immediate,
+) : DisposableHandle {
+    private val scope = CoroutineScope(SupervisorJob() + mainImmediateDispatcher)
+
+    fun dismiss(notification: Notification, onResultListener: OnResultListener) {
+        notificationDismisser.dismiss(notification)
+            .onEach { outcome -> onResultListener.onResult(outcome) }
+            .launchIn(scope)
+    }
+
+    override fun dispose() {
+        scope.cancel()
+    }
+
+    fun interface OnResultListener {
+        fun onResult(outcome: Outcome<Success<Notification>, Failure<Notification>>)
+    }
+}

feature/notification/api/src/commonMain/kotlin/net/thunderbird/feature/notification/api/receiver/NotificationNotifier.kt

@@ -4,21 +4,40 @@ import net.thunderbird.feature.notification.api.NotificationId
 import net.thunderbird.feature.notification.api.content.Notification
 
 /**
- * Interface for displaying notifications.
+ * Abstraction for components that present and manage a specific kind of notification.
  *
- * This is a sealed interface, meaning that all implementations must be declared in this file.
+ * Implementations are responsible for rendering notifications (e.g., system tray notifications,
+ * in-app notifications) and for dismissing them when requested. The generic type parameter
+ * allows an implementation to declare which [Notification] sub-type it can handle.
  *
- * @param TNotification The type of notification to display.
+ * Type parameters:
+ * @param TNotification The specific subtype of [Notification] this notifier can display. The
+ * contravariant `in` variance allows a notifier for a base type to also accept its subtypes.
  */
 interface NotificationNotifier<in TNotification : Notification> {
     /**
-     * Shows a notification to the user.
+     * Displays or updates a notification associated with the given [id].
      *
-     * @param id The notification id. Mostly used by System Notifications.
-     * @param notification The notification to show.
+     * Implementations should render [notification] according to their medium. If a notification
+     * with the same [id] is already visible, this call should update/replace it when supported
+     * by the underlying mechanism.
+     *
+     * @param id A stable identifier that correlates to this notification instance across updates
+     * and dismissal. Often maps to a system notification ID when using platform notifications.
+     * @param notification The domain model describing what to present to the user.
      */
     suspend fun show(id: NotificationId, notification: TNotification)
 
+    /**
+     * Dismisses the notification previously shown with [id].
+     *
+     * If no notification is currently displayed for [id], implementations should treat this as a
+     * no-op.
+     *
+     * @param id The identifier of the notification to dismiss.
+     */
+    suspend fun dismiss(id: NotificationId)
+
     /**
      * Disposes of any resources used by the notifier.
      *

feature/notification/api/src/commonMain/kotlin/net/thunderbird/feature/notification/api/ui/host/InAppNotificationHostStateHolder.kt

@@ -82,6 +82,21 @@ class InAppNotificationHostStateHolder(private val enabled: ImmutableSet<Display
         }
     }
 
+    /**
+     * Dismisses all visual representations of the given in-app notification.
+     *
+     * This function will attempt to dismiss the global banner, inline banners,
+     * and snackbar associated with the provided notification.
+     *
+     * @param notification The [InAppNotification] to dismiss.
+     */
+    fun dismiss(notification: InAppNotification) {
+        val data = notification.toInAppNotificationData()
+        data.bannerInlineVisuals.singleOrNull()?.let(::dismiss)
+        data.bannerGlobalVisual?.let(::dismiss)
+        data.snackbarVisual?.let(::dismiss)
+    }
+
     /**
      * Dismisses the given in-app notification visual.
      *

feature/notification/impl/src/androidMain/kotlin/net/thunderbird/feature/notification/impl/receiver/AndroidSystemNotificationNotifier.kt

@@ -33,6 +33,11 @@ internal class AndroidSystemNotificationNotifier(
         notificationManager.notify(id.value, androidNotification)
     }
 
+    override suspend fun dismiss(id: NotificationId) {
+        logger.debug(TAG) { "dismiss() called with: id = $id" }
+        notificationManager.cancel(id.value)
+    }
+
     override fun dispose() {
         logger.debug(TAG) { "dispose() called" }
     }

feature/notification/impl/src/commonMain/kotlin/net/thunderbird/feature/notification/impl/DefaultNotificationManager.kt

@@ -0,0 +1,19 @@
+package net.thunderbird.feature.notification.impl
+
+import net.thunderbird.feature.notification.api.NotificationManager
+import net.thunderbird.feature.notification.api.dismisser.NotificationDismisser
+import net.thunderbird.feature.notification.api.sender.NotificationSender
+
+/**
+ * Default implementation of [NotificationManager].
+ *
+ * This class acts as a central point for managing notifications, delegating sending and dismissing
+ * operations to the provided [NotificationSender] and [NotificationDismisser] respectively.
+ *
+ * @param notificationSender The [NotificationSender] responsible for displaying notifications.
+ * @param notificationDismisser The [NotificationDismisser] responsible for removing notifications.
+ */
+class DefaultNotificationManager(
+    private val notificationSender: NotificationSender,
+    private val notificationDismisser: NotificationDismisser,
+) : NotificationManager, NotificationSender by notificationSender, NotificationDismisser by notificationDismisser

feature/notification/impl/src/commonMain/kotlin/net/thunderbird/feature/notification/impl/DefaultNotificationRegistry.kt

@@ -57,4 +57,12 @@ class DefaultNotificationRegistry : NotificationRegistry {
     override fun unregister(notification: Notification) {
         _registrar.remove(notification)
     }
+
+    override fun contains(notification: Notification): Boolean {
+        return _registrar.containsKey(notification)
+    }
+
+    override fun contains(notificationId: NotificationId): Boolean {
+        return _registrar.containsValue(notificationId)
+    }
 }