Custom notifications

README.md

@@ -411,6 +411,48 @@ assistInstance.getState()
   })
 ```
 
+### `notify(type, message, options)`
+
+Trigger a custom UI notification
+
+#### Parameters
+
+`type` - `String`: One of: ['success', 'pending', 'error'] (**Required**)
+
+`message` - `String`: The message to display in the notification. HTML can be embedded in the string. (**Required**)
+
+`options` - `Object`: Further customize the notification
+
+```js
+options = {
+  customTimeout: Number, // Specify how many ms the notification should exist. Set to -1 for no timeout.
+  customCode: String // An identifier for this notify call
+}
+```
+
+options.customTimeout defaults: { success: 2000, pending: 5000, error: 5000 }
+
+#### Returns
+
+`Function`
+
+- a function that when called will dismiss the notification
+
+#### Examples
+
+```javascript
+// Display a success notification with an embedded link for 5000ms
+assistInstance.notify('success', 'Operation was a success! Click <a href="https://example.com" target="_blank">here</a> to view more', { customTimeout: 5000 });
+
+// Display a pending notification, load data from an imaginary backend
+// and dismiss the pending notification only when the data is loaded
+const dismiss = assistInstance.notify('pending', 'Loading data...', { customTimeout: -1 });
+myEventEmitter.emit('fetch-data-from-backend')
+myEventEmitter.on('data-from-backend-loaded', () => {
+  dismiss()
+})
+```
+
 ## Contribute
 
 ### Installing Dependencies

src/__integration-tests__/ui-rendering/__snapshots__/index.test.js.snap

@@ -2181,3 +2181,67 @@ exports[`dom-rendering event onboard-welcomeUser should trigger correct DOM rend
     </div>
   </div>"
 `;
+
+exports[`dom-rendering event userInitiatedNotify-error should trigger correct DOM render 1`] = `
+"
+
+  <div class=\\"\\" id=\\"blocknative-notifications\\" style=\\"transform: translate(600px); right: 0px; bottom: 0px;\\"><div class=\\"bn-notifications-scroll\\" style=\\"overflow-y: initial; height: auto;\\"><ul class=\\"bn-notifications\\"><li class=\\"bn-notification bn-failed bn-error bn-undefined \\" style=\\"transform: translate(600px);\\">
+		<span class=\\"bn-status-icon \\">
+
+		</span>
+		<div class=\\"bn-notification-info\\">
+			<p>error custom msg</p>
+			<p class=\\"bn-notification-meta\\">
+				<a href=\\"#\\" class=\\"bn-timestamp\\">12:00 AM</a>
+				<span class=\\"bn-duration bn-duration-hidden\\"> - 
+					<i class=\\"bn-clock\\"></i>
+					<span class=\\"bn-duration-time\\">NaN sec</span>
+				</span>
+			</p>
+		</div>
+	</li></ul></div><a class=\\"\\" id=\\"bn-transaction-branding\\" href=\\"https://www.blocknative.com/\\" target=\\"_blank\\" style=\\"float: right;\\"></a></div>"
+`;
+
+exports[`dom-rendering event userInitiatedNotify-pending should trigger correct DOM render 1`] = `
+"
+
+  <div class=\\"\\" id=\\"blocknative-notifications\\" style=\\"transform: translate(600px); right: 0px; bottom: 0px;\\"><div class=\\"bn-notifications-scroll\\" style=\\"overflow-y: initial; height: auto;\\"><ul class=\\"bn-notifications\\"><li class=\\"bn-notification bn-progress bn-pending bn-cf7fc5a7-1498-419e-8bf9-654d06af5534 \\" style=\\"transform: translate(600px);\\">
+		<span class=\\"bn-status-icon \\">
+      <div class=\\"progress-tooltip \\">
+				<div class=\\"progress-tooltip-inner\\">
+					You will be notified when this transaction is completed.
+				</div>
+			</div>
+		</span>
+		<div class=\\"bn-notification-info\\">
+			<p>pending custom msg</p>
+			<p class=\\"bn-notification-meta\\">
+				<a href=\\"#\\" class=\\"bn-timestamp\\">12:00 AM</a>
+				<span class=\\"bn-duration\\"> - 
+					<i class=\\"bn-clock\\"></i>
+					<span class=\\"bn-duration-time\\">606 min</span>
+				</span>
+			</p>
+		</div>
+	</li></ul></div><a class=\\"\\" id=\\"bn-transaction-branding\\" href=\\"https://www.blocknative.com/\\" target=\\"_blank\\" style=\\"float: right;\\"></a></div>"
+`;
+
+exports[`dom-rendering event userInitiatedNotify-success should trigger correct DOM render 1`] = `
+"
+
+  <div class=\\"\\" id=\\"blocknative-notifications\\" style=\\"transform: translate(600px); right: 0px; bottom: 0px;\\"><div class=\\"bn-notifications-scroll\\" style=\\"overflow-y: initial; height: auto;\\"><ul class=\\"bn-notifications\\"><li class=\\"bn-notification bn-complete bn-success bn-undefined \\" style=\\"transform: translate(600px);\\">
+		<span class=\\"bn-status-icon \\">
+
+		</span>
+		<div class=\\"bn-notification-info\\">
+			<p>success custom msg</p>
+			<p class=\\"bn-notification-meta\\">
+				<a href=\\"#\\" class=\\"bn-timestamp\\">12:00 AM</a>
+				<span class=\\"bn-duration bn-duration-hidden\\"> - 
+					<i class=\\"bn-clock\\"></i>
+					<span class=\\"bn-duration-time\\">NaN sec</span>
+				</span>
+			</p>
+		</div>
+	</li></ul></div><a class=\\"\\" id=\\"bn-transaction-branding\\" href=\\"https://www.blocknative.com/\\" target=\\"_blank\\" style=\\"float: right;\\"></a></div>"
+`;

src/__integration-tests__/ui-rendering/event-definitions.js

@@ -32,6 +32,25 @@ const mockTxFactory = ({ nonce, startTime } = {}) => {
  * }
  */
 export default {
+  success: {
+    categories: ['userInitiatedNotify'],
+    customStates: [
+      { config: { messages: { success: () => 'success custom msg' } } }
+    ]
+  },
+  pending: {
+    categories: ['userInitiatedNotify'],
+    params: { transaction: mockTxFactory({ startTime: true }) },
+    customStates: [
+      { config: { messages: { pending: () => 'pending custom msg' } } }
+    ]
+  },
+  error: {
+    categories: ['userInitiatedNotify'],
+    customStates: [
+      { config: { messages: { error: () => 'error custom msg' } } }
+    ]
+  },
   browserFail: {
     categories: ['onboard'],
     clickHandlers: new Set(['onClose'])

src/__tests__/js/init.test.js

@@ -41,6 +41,7 @@ test('Returns the dassist object', () => {
   expect(assist).toHaveProperty('Contract')
   expect(assist).toHaveProperty('Transaction')
   expect(assist).toHaveProperty('getState')
+  expect(assist).toHaveProperty('notify')
 })
 
 test('Fails if we try to decorate without a web3 instance', () => {

src/__tests__/logic/user-initiated-notify.test.js

@@ -0,0 +1,121 @@
+import da from '~/js'
+import userInitiatedNotify, {
+  defaultTimeout
+} from '~/js/logic/user-initiated-notify'
+import { updateState, initialState, state } from '~/js/helpers/state'
+import * as events from '~/js/helpers/events'
+
+jest.useFakeTimers()
+const ONE_MIN_IN_MS = 60000
+
+describe('user-initiated-notify.js', () => {
+  describe('userInitiatedNotify', () => {
+    const message = 'some-msg'
+    const customEventCodes = ['success', 'pending', 'error']
+    test('throws if eventCode is invalid', () => {
+      expect(() => userInitiatedNotify('invalid code', message)).toThrow()
+    })
+    customEventCodes.forEach(eventCode => {
+      describe(`type ${eventCode}`, () => {
+        test('throws if customTimeout is not a number', () => {
+          expect(() =>
+            userInitiatedNotify(eventCode, message, { customTimeout: '123' })
+          ).toThrow()
+        })
+        test('throws if customCode is not a string', () => {
+          expect(() =>
+            userInitiatedNotify(eventCode, message, { customCode: 123 })
+          ).toThrow()
+        })
+        test('throws if customCode is greater than 24 characters', () => {
+          const customCode = '0123456789012345678901234'
+          expect(() =>
+            userInitiatedNotify(eventCode, message, { customCode })
+          ).toThrow()
+        })
+        test('when no customCode is specified the correct default is passed to logEvent', () => {
+          const logEventSpy = jest
+            .spyOn(events.lib, 'logEvent')
+            .mockImplementation(() => {})
+          userInitiatedNotify(eventCode, message)
+          const lastCallIndex = logEventSpy.mock.calls.length - 1
+          expect(logEventSpy.mock.calls[lastCallIndex][0]).toMatchObject({
+            customCode: `custom ${eventCode}`
+          })
+          logEventSpy.mockRestore()
+        })
+        test('when a customCode is specified it is included in the object passed to logEvent', () => {
+          const customCode = '123'
+          const logEventSpy = jest
+            .spyOn(events.lib, 'logEvent')
+            .mockImplementation(() => {})
+          userInitiatedNotify(eventCode, message, { customCode })
+          const lastCallIndex = logEventSpy.mock.calls.length - 1
+          expect(logEventSpy.mock.calls[lastCallIndex][0]).toMatchObject({
+            customCode
+          })
+          logEventSpy.mockRestore()
+        })
+        test('triggers notification and defaults to correct timeout', () => {
+          userInitiatedNotify('success', message)
+          // notification should exist after being triggered
+          expect(
+            state.iframeDocument.body.innerHTML.includes(message)
+          ).toBeTruthy()
+          // advance time past the defaultTimeout
+          jest.advanceTimersByTime(defaultTimeout(eventCode) + 500)
+          // notification should have timed out
+          expect(
+            state.iframeDocument.body.innerHTML.includes(message)
+          ).toBeFalsy()
+        })
+        test(`doesn't throw if dismiss is called after the notification has already timed out`, () => {
+          expect(() => {
+            const notify = userInitiatedNotify(eventCode, message, {
+              customTimeout: 100
+            })
+            setTimeout(() => {
+              notify()
+            }, 1000)
+            jest.advanceTimersByTime(500) // trigger timeout
+            jest.runOnlyPendingTimers() // trigger notify
+          }).not.toThrow()
+        })
+        test(`doesn't throw if notification times out after dismiss was already called`, () => {
+          expect(() => {
+            const notify = userInitiatedNotify(eventCode, message, {
+              customTimeout: 1000
+            })
+            setTimeout(() => {
+              notify()
+            }, 100)
+            jest.advanceTimersByTime(500) // trigger notify
+            jest.runOnlyPendingTimers() // trigger timeout
+          }).not.toThrow()
+        })
+        test(`setting customTimeout overrides the default timeout`, () => {
+          userInitiatedNotify(eventCode, message, { customTimeout: 500 })
+          jest.advanceTimersByTime(1000)
+          expect(
+            state.iframeDocument.body.innerHTML.includes(message)
+          ).toBeFalsy()
+        })
+        test(`setting customTimeout to -1 stops it automatically timing out`, () => {
+          userInitiatedNotify(eventCode, message, { customTimeout: -1 })
+          jest.advanceTimersByTime(ONE_MIN_IN_MS)
+          expect(
+            state.iframeDocument.body.innerHTML.includes(message)
+          ).toBeTruthy()
+        })
+      })
+    })
+  })
+})
+
+beforeEach(() => {
+  da.init({ dappId: '123' })
+})
+
+afterEach(() => {
+  updateState(initialState)
+})

src/js/helpers/events.js

@@ -15,8 +15,20 @@ export function handleEvent(eventObj, clickHandlers) {
     eventCode === 'txSpeedUp' ||
     eventCode === 'txCancel'
 
-  // If not a server event then log it
-  !serverEvent && lib.logEvent(eventObj)
+  let eventToLog = { ...eventObj }
+
+  // If dealing with a custom notification the logged event
+  // should have it's event and category code changed
+  if (categoryCode === 'userInitiatedNotify') {
+    eventToLog = {
+      ...eventToLog,
+      categoryCode: 'custom',
+      eventCode: 'txNotification'
+    }
+  }
+
+  // Log everything that isn't a server event
+  !serverEvent && lib.logEvent(eventToLog)
 
   // If tx status is 'completed', UI has been already handled
   if (eventCode === 'txConfirmed' || eventCode === 'txConfirmedClient') {

src/js/helpers/utilities.js

@@ -106,6 +106,7 @@ export function eventCodeToType(eventCode) {
     case 'txSent':
     case 'txSpeedUp':
     case 'txCancel':
+    case 'pending':
       return 'progress'
     case 'txSendFail':
     case 'txStall':
@@ -114,9 +115,11 @@ export function eventCodeToType(eventCode) {
     case 'txRepeat':
     case 'txAwaitingApproval':
     case 'txConfirmReminder':
+    case 'error':
       return 'failed'
     case 'txConfirmed':
     case 'txConfirmedClient':
+    case 'success':
       return 'complete'
     default:
       return undefined

src/js/index.js

@@ -4,6 +4,7 @@ import assistStyles from '~/css/styles.css'
 
 import { state, updateState } from './helpers/state'
 import { handleEvent } from './helpers/events'
+import notify from './logic/user-initiated-notify'
 import {
   legacyCall,
   legacySend,
@@ -96,7 +97,8 @@ function init(config) {
     onboard,
     Contract,
     Transaction,
-    getState
+    getState,
+    notify
   }
 
   getState().then(state => {

src/js/logic/user-initiated-notify.js

@@ -0,0 +1,56 @@
+import uuid from 'uuid/v4'
+import { handleEvent } from '~/js/helpers/events'
+import { getAllByQuery, removeNotification } from '~/js/views/dom'
+
+export const defaultTimeout = eventCode => {
+  if (eventCode === 'success') return 2000
+  if (eventCode === 'pending') return 5000
+  if (eventCode === 'error') return 5000
+  throw new Error('Invalid eventCode')
+}
+
+// Allow the developer to spawn custom notifications
+export default function userInitiatedNotify(
+  eventCode,
+  message,
+  {
+    customTimeout = defaultTimeout(eventCode),
+    customCode = `custom ${eventCode}`
+  } = {}
+) {
+  // Validate message
+  if (typeof message !== 'string') throw new Error('Message is required')
+  // Validate eventCode
+  if (
+    eventCode !== 'success' &&
+    eventCode !== 'pending' &&
+    eventCode !== 'error'
+  )
+    throw new Error(`eventCode must be one of: ['success', 'pending', 'error']`)
+  // Validate customTimeout
+  if (customTimeout && typeof customTimeout !== 'number')
+    throw new Error('customTimeout must be a number')
+  // Validate customCode
+  if (customCode) {
+    if (typeof customCode !== 'string')
+      throw new Error('customCode must be a string')
+    if (customCode.length > 24)
+      throw new Error('customCode must be less than 24 characters')
+  }
+
+  const id = uuid()
+  handleEvent({
+    eventCode,
+    categoryCode: 'userInitiatedNotify',
+    transaction: { id, startTime: Date.now() },
+    inlineCustomMsgs: { [eventCode]: () => message },
+    customTimeout: customTimeout !== -1 && customTimeout,
+    customCode
+  })
+
+  // Return a callback the user can use to dismiss the notification
+  const notification = getAllByQuery(`.bn-${id}`)[0]
+  return () => {
+    removeNotification(notification)
+  }
+}