User Notifications

The User Notifications system in Ghostbird provides users with timely feedback about the connection status with the GhostText server. This feature, introduced in version 0.3.0, is designed to be non-intrusive and is configurable through the add-on's options page. Notifications are used to signal successful connections, disconnections, and errors, enhancing the user experience by making the state of the extension clear.

Sources: README.md, src/ghosttext-adaptor/api.ts:60-65

Architecture and Components

The notification system is built on a decoupled architecture, adhering to the Dependency Inversion Principle. This is achieved by defining interfaces that are implemented by concrete classes, allowing for easier testing and maintenance.

Permissions

To display system notifications, the add-on must request the notifications permission in its manifest file.

// manifest_template.json:19-25
"permissions": [
  "alarms",
  "compose",
  "notifications",
  "menus",
  "scripting",
  "storage"
],

This declaration is crucial for the entire notification feature to function within the Thunderbird environment.

Sources: manifest_template.json:19-25

Core Components

The system is comprised of three main components: an interface, an implementation, and a consumer.

1. INotificationTray (Interface): Defines the contract for showing notifications. This abstraction allows different parts of the application to request a notification without being tied to a specific implementation.
   Sources: src/ghosttext-adaptor/api.ts:4-8

2. NotificationTray (Implementation): The concrete implementation of INotificationTray. It uses the messenger.notifications.create WebExtension API to display a native system notification.
   Sources: src/thunderbird/background_util/notification_tray.ts:10-23

3. ComposeActionNotifier (Consumer): This class listens for application events (e.g., connection, disconnection, error) and decides whether to trigger a notification. It first checks the user's preferences via IStoredOptionsLoader before calling the INotificationTray service.
   Sources: src/app-background/compose_action_notifier.ts

The following diagram illustrates the relationship between these components.

This diagram shows that ComposeActionNotifier depends on the INotificationTray and IStoredOptionsLoader interfaces, not on concrete implementations.

Sources: src/ghosttext-adaptor/api.ts:4-8, src/thunderbird/background_util/notification_tray.ts:10-23, src/app-background/compose_action_notifier.ts:11-20

Notification Flow

When a relevant event occurs, such as a connection to the GhostText server, the ComposeActionNotifier orchestrates the process of displaying a notification.

The sequence diagram below details the flow:

This flow ensures that notifications are only shown if the user has explicitly enabled them in the settings. The Notifier checks the configuration before instructing the Tray to create the notification via the Thunderbird API.

Sources: src/app-background/compose_action_notifier.ts:22-30, src/thunderbird/background_util/notification_tray.ts:15-22

Configuration

Users can enable or disable notifications through the Ghostbird options page. This setting is persisted in the browser's local storage.

Stored Options

The structure for the options is defined by the StoredOptions type.

// src/ghosttext-adaptor/api.ts:60-65
export type StoredOptions = {
  /** The port of the GhostText server to connect to */
  serverPort: number
  /** Shows notifications when connecting or disconnecting from GhostText if true */
  enableNotifications: boolean
}

Sources: src/ghosttext-adaptor/api.ts:60-65

Options Summary

Sources: src/ghosttext-adaptor/api.ts:63-64, ext/options.css:47-49

In-Page UI Feedback

In addition to system notifications, the options page itself provides temporary, notification-like feedback for user actions. When settings are saved, a "Saved" or "Error" message is briefly displayed and then fades out. This is handled purely through CSS animations.

/* ext/options.css:52-60 */
.progress {
  &.saved::before {
    content: "__MSG_options_saved__";
    color: var(--color-success-default);
    animation: fadeOut 1s forwards;
  }
  &.error::before {
    content: "__MSG_options_error__";
    color: var(--color-danger-default);
    animation: fadeOut 1s forwards;
  }
}

This provides immediate confirmation of the user's action directly within the UI.

Sources: ext/options.css:52-60