The notifications system of Roundcube Next shall be the primary handler for `shell.notify` events and provide the visual presentation of notifications according to the specified type and situation. Consider the following examples:
* //Warning//: User login failed
* //Confirmation//: Message moved to folder X
* //Error//: Failed to save event to calendar
* //Info//: Max B became online
* //Loading//: Sending message...
* //Notification//: New message from Sam Foo
In order to cover the various use-cases where an app wants to notify the user about a particular event or situation, the event argument should be a `Notification` object specifying the type of the message as well as additional details regarding its presentation or interaction.
The exact model is drafted [[#Notification Model | below]] but let's start with some use-cases the notification system should be able to serve:
== User Stories ==
=== User Login ===
# User submits the login form
# The server denies authentication
# A //warning// is displayed to inform that authentication failed
# The user re-types her password
# The //warning// vanishes when submitting the login form again
=== New message arrived ===
# The mail app checks for new messages
# Two new messages arrived in the Inbox
# The webmail window does not have focus but the user has enabled desktop notifications
# Using the Notifications API of the browser, a notification box is displayed on the users desktop
=== User accepts event invitation ===
# Jane clicks on the "Accept" button of an event invitation
# The event is added to her calendar and a reply is sent to the organizer
# Jane gets to see two messages saying
- Successfully saved event to calendar "Personal"
- Failed to send the response to this event invitation
# The first confirmation message vanishes after 10 seconds
# The warning remains visible until Jane closes the box
== Application requirements ==
A component triggering a notification event should have some possibilities to interact with the displayed notification in some ways.
* Assign an ID/Tag in order to revoke/hide the message later on (example: hide warning about failed login attempt if login finally succeeds on the seconds try)
* Register callback functions to get informed when the user clicks or closes the notification box
* Supply structured information like `type`, `title`, `body` or even `sound`
* Control the time of appearance: auto (according to type), seconds, sticky
== Notification Model ==
The suggested model is inspired by the [Browsers Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notification).
```lang=js
{
type: "info|warn|error|alert|success|wait|notify",
title: "The notification title/message",
body: "(optional) body with additional information",
timeout: 5000, // ms
sticky: true|false,
tag: "identifier",
icon: "(optional) icon to be displayed",
onclick: function() { /* callback if clicked */ },
onclose: function() { /* callback if closed */ },
}
```
== Pubsub events ==
`shell.notify`
Triggers a new notification. Takes a `Notification`object as argument
`shell.notify.revoke`
Revokes a previously triggered notification (i.e. hides the box). Takes a `String` argument denoting the `tag` of the notification(s) to be revoked.