Merge #15678: Decaffeinate Notification, NotificationManager, & related specs

This commit is contained in:
Jason Rudolph
2017-09-19 08:27:09 -04:00
committed by GitHub
8 changed files with 464 additions and 386 deletions

View File

@@ -1,183 +0,0 @@
{Emitter} = require 'event-kit'
Notification = require '../src/notification'
# Public: A notification manager used to create {Notification}s to be shown
# to the user.
#
# An instance of this class is always available as the `atom.notifications`
# global.
module.exports =
class NotificationManager
constructor: ->
@notifications = []
@emitter = new Emitter
###
Section: Events
###
# Public: Invoke the given callback after a notification has been added.
#
# * `callback` {Function} to be called after the notification is added.
# * `notification` The {Notification} that was added.
#
# Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
onDidAddNotification: (callback) ->
@emitter.on 'did-add-notification', callback
###
Section: Adding Notifications
###
# Public: Add a success notification.
#
# * `message` A {String} message
# * `options` (optional) An options {Object} with the following keys:
# * `buttons` (optional) An {Array} of {Object} where each {Object} has the
# following options:
# * `className` (optional) {String} a class name to add to the button's
# default class name (`btn btn-success`).
# * `onDidClick` (optional) {Function} callback to call when the button
# has been clicked. The context will be set to the
# {NotificationElement} instance.
# * `text` {String} inner text for the button
# * `description` (optional) A Markdown {String} containing a longer
# description about the notification. By default, this **will not**
# preserve newlines and whitespace when it is rendered.
# * `detail` (optional) A plain-text {String} containing additional details
# about the notification. By default, this **will** preserve newlines
# and whitespace when it is rendered.
# * `dismissable` (optional) A {Boolean} indicating whether this
# notification can be dismissed by the user. Defaults to `false`.
# * `icon` (optional) A {String} name of an icon from Octicons to display
# in the notification header. Defaults to `'check'`.
addSuccess: (message, options) ->
@addNotification(new Notification('success', message, options))
# Public: Add an informational notification.
#
# * `message` A {String} message
# * `options` (optional) An options {Object} with the following keys:
# * `buttons` (optional) An {Array} of {Object} where each {Object} has the
# following options:
# * `className` (optional) {String} a class name to add to the button's
# default class name (`btn btn-info`).
# * `onDidClick` (optional) {Function} callback to call when the button
# has been clicked. The context will be set to the
# {NotificationElement} instance.
# * `text` {String} inner text for the button
# * `description` (optional) A Markdown {String} containing a longer
# description about the notification. By default, this **will not**
# preserve newlines and whitespace when it is rendered.
# * `detail` (optional) A plain-text {String} containing additional details
# about the notification. By default, this **will** preserve newlines
# and whitespace when it is rendered.
# * `dismissable` (optional) A {Boolean} indicating whether this
# notification can be dismissed by the user. Defaults to `false`.
# * `icon` (optional) A {String} name of an icon from Octicons to display
# in the notification header. Defaults to `'info'`.
addInfo: (message, options) ->
@addNotification(new Notification('info', message, options))
# Public: Add a warning notification.
#
# * `message` A {String} message
# * `options` (optional) An options {Object} with the following keys:
# * `buttons` (optional) An {Array} of {Object} where each {Object} has the
# following options:
# * `className` (optional) {String} a class name to add to the button's
# default class name (`btn btn-warning`).
# * `onDidClick` (optional) {Function} callback to call when the button
# has been clicked. The context will be set to the
# {NotificationElement} instance.
# * `text` {String} inner text for the button
# * `description` (optional) A Markdown {String} containing a longer
# description about the notification. By default, this **will not**
# preserve newlines and whitespace when it is rendered.
# * `detail` (optional) A plain-text {String} containing additional details
# about the notification. By default, this **will** preserve newlines
# and whitespace when it is rendered.
# * `dismissable` (optional) A {Boolean} indicating whether this
# notification can be dismissed by the user. Defaults to `false`.
# * `icon` (optional) A {String} name of an icon from Octicons to display
# in the notification header. Defaults to `'alert'`.
addWarning: (message, options) ->
@addNotification(new Notification('warning', message, options))
# Public: Add an error notification.
#
# * `message` A {String} message
# * `options` (optional) An options {Object} with the following keys:
# * `buttons` (optional) An {Array} of {Object} where each {Object} has the
# following options:
# * `className` (optional) {String} a class name to add to the button's
# default class name (`btn btn-error`).
# * `onDidClick` (optional) {Function} callback to call when the button
# has been clicked. The context will be set to the
# {NotificationElement} instance.
# * `text` {String} inner text for the button
# * `description` (optional) A Markdown {String} containing a longer
# description about the notification. By default, this **will not**
# preserve newlines and whitespace when it is rendered.
# * `detail` (optional) A plain-text {String} containing additional details
# about the notification. By default, this **will** preserve newlines
# and whitespace when it is rendered.
# * `dismissable` (optional) A {Boolean} indicating whether this
# notification can be dismissed by the user. Defaults to `false`.
# * `icon` (optional) A {String} name of an icon from Octicons to display
# in the notification header. Defaults to `'flame'`.
# * `stack` (optional) A preformatted {String} with stack trace information
# describing the location of the error.
addError: (message, options) ->
@addNotification(new Notification('error', message, options))
# Public: Add a fatal error notification.
#
# * `message` A {String} message
# * `options` (optional) An options {Object} with the following keys:
# * `buttons` (optional) An {Array} of {Object} where each {Object} has the
# following options:
# * `className` (optional) {String} a class name to add to the button's
# default class name (`btn btn-error`).
# * `onDidClick` (optional) {Function} callback to call when the button
# has been clicked. The context will be set to the
# {NotificationElement} instance.
# * `text` {String} inner text for the button
# * `description` (optional) A Markdown {String} containing a longer
# description about the notification. By default, this **will not**
# preserve newlines and whitespace when it is rendered.
# * `detail` (optional) A plain-text {String} containing additional details
# about the notification. By default, this **will** preserve newlines
# and whitespace when it is rendered.
# * `dismissable` (optional) A {Boolean} indicating whether this
# notification can be dismissed by the user. Defaults to `false`.
# * `icon` (optional) A {String} name of an icon from Octicons to display
# in the notification header. Defaults to `'bug'`.
# * `stack` (optional) A preformatted {String} with stack trace information
# describing the location of the error.
addFatalError: (message, options) ->
@addNotification(new Notification('fatal', message, options))
add: (type, message, options) ->
@addNotification(new Notification(type, message, options))
addNotification: (notification) ->
@notifications.push(notification)
@emitter.emit('did-add-notification', notification)
notification
###
Section: Getting Notifications
###
# Public: Get all the notifications.
#
# Returns an {Array} of {Notification}s.
getNotifications: -> @notifications.slice()
###
Section: Managing Notifications
###
clear: ->
@notifications = []

206
src/notification-manager.js Normal file
View File

@@ -0,0 +1,206 @@
const {Emitter} = require('event-kit')
const Notification = require('../src/notification')
// Public: A notification manager used to create {Notification}s to be shown
// to the user.
//
// An instance of this class is always available as the `atom.notifications`
// global.
module.exports =
class NotificationManager {
constructor () {
this.notifications = []
this.emitter = new Emitter()
}
/*
Section: Events
*/
// Public: Invoke the given callback after a notification has been added.
//
// * `callback` {Function} to be called after the notification is added.
// * `notification` The {Notification} that was added.
//
// Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
onDidAddNotification (callback) {
return this.emitter.on('did-add-notification', callback)
}
/*
Section: Adding Notifications
*/
// Public: Add a success notification.
//
// * `message` A {String} message
// * `options` (optional) An options {Object} with the following keys:
// * `buttons` (optional) An {Array} of {Object} where each {Object} has
// the following options:
// * `className` (optional) {String} a class name to add to the button's
// default class name (`btn btn-success`).
// * `onDidClick` (optional) {Function} callback to call when the button
// has been clicked. The context will be set to the
// {NotificationElement} instance.
// * `text` {String} inner text for the button
// * `description` (optional) A Markdown {String} containing a longer
// description about the notification. By default, this **will not**
// preserve newlines and whitespace when it is rendered.
// * `detail` (optional) A plain-text {String} containing additional
// details about the notification. By default, this **will** preserve
// newlines and whitespace when it is rendered.
// * `dismissable` (optional) A {Boolean} indicating whether this
// notification can be dismissed by the user. Defaults to `false`.
// * `icon` (optional) A {String} name of an icon from Octicons to display
// in the notification header. Defaults to `'check'`.
//
// Returns the {Notification} that was added.
addSuccess (message, options) {
return this.addNotification(new Notification('success', message, options))
}
// Public: Add an informational notification.
//
// * `message` A {String} message
// * `options` (optional) An options {Object} with the following keys:
// * `buttons` (optional) An {Array} of {Object} where each {Object} has
// the following options:
// * `className` (optional) {String} a class name to add to the button's
// default class name (`btn btn-info`).
// * `onDidClick` (optional) {Function} callback to call when the button
// has been clicked. The context will be set to the
// {NotificationElement} instance.
// * `text` {String} inner text for the button
// * `description` (optional) A Markdown {String} containing a longer
// description about the notification. By default, this **will not**
// preserve newlines and whitespace when it is rendered.
// * `detail` (optional) A plain-text {String} containing additional
// details about the notification. By default, this **will** preserve
// newlines and whitespace when it is rendered.
// * `dismissable` (optional) A {Boolean} indicating whether this
// notification can be dismissed by the user. Defaults to `false`.
// * `icon` (optional) A {String} name of an icon from Octicons to display
// in the notification header. Defaults to `'info'`.
//
// Returns the {Notification} that was added.
addInfo (message, options) {
return this.addNotification(new Notification('info', message, options))
}
// Public: Add a warning notification.
//
// * `message` A {String} message
// * `options` (optional) An options {Object} with the following keys:
// * `buttons` (optional) An {Array} of {Object} where each {Object} has
// the following options:
// * `className` (optional) {String} a class name to add to the button's
// default class name (`btn btn-warning`).
// * `onDidClick` (optional) {Function} callback to call when the button
// has been clicked. The context will be set to the
// {NotificationElement} instance.
// * `text` {String} inner text for the button
// * `description` (optional) A Markdown {String} containing a longer
// description about the notification. By default, this **will not**
// preserve newlines and whitespace when it is rendered.
// * `detail` (optional) A plain-text {String} containing additional
// details about the notification. By default, this **will** preserve
// newlines and whitespace when it is rendered.
// * `dismissable` (optional) A {Boolean} indicating whether this
// notification can be dismissed by the user. Defaults to `false`.
// * `icon` (optional) A {String} name of an icon from Octicons to display
// in the notification header. Defaults to `'alert'`.
//
// Returns the {Notification} that was added.
addWarning (message, options) {
return this.addNotification(new Notification('warning', message, options))
}
// Public: Add an error notification.
//
// * `message` A {String} message
// * `options` (optional) An options {Object} with the following keys:
// * `buttons` (optional) An {Array} of {Object} where each {Object} has
// the following options:
// * `className` (optional) {String} a class name to add to the button's
// default class name (`btn btn-error`).
// * `onDidClick` (optional) {Function} callback to call when the button
// has been clicked. The context will be set to the
// {NotificationElement} instance.
// * `text` {String} inner text for the button
// * `description` (optional) A Markdown {String} containing a longer
// description about the notification. By default, this **will not**
// preserve newlines and whitespace when it is rendered.
// * `detail` (optional) A plain-text {String} containing additional
// details about the notification. By default, this **will** preserve
// newlines and whitespace when it is rendered.
// * `dismissable` (optional) A {Boolean} indicating whether this
// notification can be dismissed by the user. Defaults to `false`.
// * `icon` (optional) A {String} name of an icon from Octicons to display
// in the notification header. Defaults to `'flame'`.
// * `stack` (optional) A preformatted {String} with stack trace
// information describing the location of the error.
//
// Returns the {Notification} that was added.
addError (message, options) {
return this.addNotification(new Notification('error', message, options))
}
// Public: Add a fatal error notification.
//
// * `message` A {String} message
// * `options` (optional) An options {Object} with the following keys:
// * `buttons` (optional) An {Array} of {Object} where each {Object} has
// the following options:
// * `className` (optional) {String} a class name to add to the button's
// default class name (`btn btn-error`).
// * `onDidClick` (optional) {Function} callback to call when the button
// has been clicked. The context will be set to the
// {NotificationElement} instance.
// * `text` {String} inner text for the button
// * `description` (optional) A Markdown {String} containing a longer
// description about the notification. By default, this **will not**
// preserve newlines and whitespace when it is rendered.
// * `detail` (optional) A plain-text {String} containing additional
// details about the notification. By default, this **will** preserve
// newlines and whitespace when it is rendered.
// * `dismissable` (optional) A {Boolean} indicating whether this
// notification can be dismissed by the user. Defaults to `false`.
// * `icon` (optional) A {String} name of an icon from Octicons to display
// in the notification header. Defaults to `'bug'`.
// * `stack` (optional) A preformatted {String} with stack trace
// information describing the location of the error.
//
// Returns the {Notification} that was added.
addFatalError (message, options) {
return this.addNotification(new Notification('fatal', message, options))
}
add (type, message, options) {
return this.addNotification(new Notification(type, message, options))
}
addNotification (notification) {
this.notifications.push(notification)
this.emitter.emit('did-add-notification', notification)
return notification
}
/*
Section: Getting Notifications
*/
// Public: Get all the notifications.
//
// Returns an {Array} of {Notification}s.
getNotifications () {
return this.notifications.slice()
}
/*
Section: Managing Notifications
*/
clear () {
this.notifications = []
}
}

View File

@@ -1,86 +0,0 @@
{Emitter} = require 'event-kit'
_ = require 'underscore-plus'
# Public: A notification to the user containing a message and type.
module.exports =
class Notification
constructor: (@type, @message, @options={}) ->
@emitter = new Emitter
@timestamp = new Date()
@dismissed = true
@dismissed = false if @isDismissable()
@displayed = false
@validate()
validate: ->
if typeof @message isnt 'string'
throw new Error("Notification must be created with string message: #{@message}")
unless _.isObject(@options) and not _.isArray(@options)
throw new Error("Notification must be created with an options object: #{@options}")
###
Section: Event Subscription
###
# Public: Invoke the given callback when the notification is dismissed.
#
# * `callback` {Function} to be called when the notification is dismissed.
#
# Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
onDidDismiss: (callback) ->
@emitter.on 'did-dismiss', callback
# Public: Invoke the given callback when the notification is displayed.
#
# * `callback` {Function} to be called when the notification is displayed.
#
# Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
onDidDisplay: (callback) ->
@emitter.on 'did-display', callback
getOptions: -> @options
###
Section: Methods
###
# Public: Returns the {String} type.
getType: -> @type
# Public: Returns the {String} message.
getMessage: -> @message
getTimestamp: -> @timestamp
getDetail: -> @options.detail
isEqual: (other) ->
@getMessage() is other.getMessage() \
and @getType() is other.getType() \
and @getDetail() is other.getDetail()
# Extended: Dismisses the notification, removing it from the UI. Calling this programmatically
# will call all callbacks added via `onDidDismiss`.
dismiss: ->
return unless @isDismissable() and not @isDismissed()
@dismissed = true
@emitter.emit 'did-dismiss', this
isDismissed: -> @dismissed
isDismissable: -> !!@options.dismissable
wasDisplayed: -> @displayed
setDisplayed: (@displayed) ->
@emitter.emit 'did-display', this
getIcon: ->
return @options.icon if @options.icon?
switch @type
when 'fatal' then 'bug'
when 'error' then 'flame'
when 'warning' then 'alert'
when 'info' then 'info'
when 'success' then 'check'

118
src/notification.js Normal file
View File

@@ -0,0 +1,118 @@
const {Emitter} = require('event-kit')
const _ = require('underscore-plus')
// Public: A notification to the user containing a message and type.
module.exports =
class Notification {
constructor (type, message, options = {}) {
this.type = type
this.message = message
this.options = options
this.emitter = new Emitter()
this.timestamp = new Date()
this.dismissed = true
if (this.isDismissable()) this.dismissed = false
this.displayed = false
this.validate()
}
validate () {
if (typeof this.message !== 'string') {
throw new Error(`Notification must be created with string message: ${this.message}`)
}
if (!_.isObject(this.options) || _.isArray(this.options)) {
throw new Error(`Notification must be created with an options object: ${this.options}`)
}
}
/*
Section: Event Subscription
*/
// Public: Invoke the given callback when the notification is dismissed.
//
// * `callback` {Function} to be called when the notification is dismissed.
//
// Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
onDidDismiss (callback) {
return this.emitter.on('did-dismiss', callback)
}
// Public: Invoke the given callback when the notification is displayed.
//
// * `callback` {Function} to be called when the notification is displayed.
//
// Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
onDidDisplay (callback) {
return this.emitter.on('did-display', callback)
}
getOptions () {
return this.options
}
/*
Section: Methods
*/
// Public: Returns the {String} type.
getType () {
return this.type
}
// Public: Returns the {String} message.
getMessage () {
return this.message
}
getTimestamp () {
return this.timestamp
}
getDetail () {
return this.options.detail
}
isEqual (other) {
return (this.getMessage() === other.getMessage()) &&
(this.getType() === other.getType()) &&
(this.getDetail() === other.getDetail())
}
// Extended: Dismisses the notification, removing it from the UI. Calling this
// programmatically will call all callbacks added via `onDidDismiss`.
dismiss () {
if (!this.isDismissable() || this.isDismissed()) return
this.dismissed = true
this.emitter.emit('did-dismiss', this)
}
isDismissed () {
return this.dismissed
}
isDismissable () {
return !!this.options.dismissable
}
wasDisplayed () {
return this.displayed
}
setDisplayed (displayed) {
this.displayed = displayed
this.emitter.emit('did-display', this)
}
getIcon () {
if (this.options.icon != null) return this.options.icon
switch (this.type) {
case 'fatal': return 'bug'
case 'error': return 'flame'
case 'warning': return 'alert'
case 'info': return 'info'
case 'success': return 'check'
}
}
}