@openfin/web-notifications-client 2.9.1-alpha-3944

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2167 @@
1
+ import OpenFin from '@openfin/core';
2
+ import { ColorSchemeType, ThemeSet } from '@openfin/ui-library';
3
+ import { DefaultTheme } from 'styled-components';
4
+
5
+ type NotificationProviderInfo = {
6
+ /**
7
+ * Unique identifier for the provider. This id must not change between sessions.
8
+ *
9
+ * @remarks A non-zero length string.
10
+ */
11
+ id: string;
12
+ /**
13
+ * A UI friendly title for the provider.
14
+ *
15
+ * @remarks A non-zero length string.
16
+ */
17
+ title: string;
18
+ /**
19
+ * Icon url for the provider.
20
+ */
21
+ icon?: string;
22
+ };
23
+
24
+ /**
25
+ * Actions are the mechanism through which notifications send messages back to the application that created them. The
26
+ * service defines a number of ways in which actions can be raised (a notification being interacted with by the user,
27
+ * being closed, expiring, etc.), and it is up to each application to decide if it wishes to be informed when each of
28
+ * these triggers occur.
29
+ *
30
+ * For an action to be raised when one of these triggers occurs, the application must specify an
31
+ * {@link NotificationActionResult|action result} for each trigger it is interested in. The application should then
32
+ * listen for when these actions are raised by listening for the {@link NotificationActionEvent|`notification-action`}
33
+ * event.
34
+ *
35
+ * This event is fired once each time an action is raised, and will contain the
36
+ * {@link NotificationActionResult|action result} the application specified for that trigger. The application may then
37
+ * use the {@link NotificationActionResult|action result} to determine which trigger occurred and respond appropriately.
38
+ *
39
+ * If an {@link NotificationActionResult|action result} is not specified for a particular trigger, or it is set to
40
+ * `null`, the application will not receive a corresponding {@link NotificationActionEvent|`notification-action`} when
41
+ * that trigger occurs.
42
+ *
43
+ * Unlike other event types, {@link NotificationActionEvent|`notification-action`} events will be buffered by the
44
+ * service until the application has added a listener for this event type, at which point it will receive all buffered
45
+ * {@link NotificationActionEvent|`notification-action`} events. The service will also attempt to restart the
46
+ * application if it is not running when the event is fired.
47
+ *
48
+ * For an overview of actions, consider the sample notification below:
49
+ * ```ts
50
+ * import {addEventListener, create} from 'openfin-notifications';
51
+ *
52
+ * // Create a notification with two buttons
53
+ * create({
54
+ * // Basic info
55
+ * title: 'Reminder',
56
+ * body: 'Event "Weekly Meeting" is starting soon...',
57
+ *
58
+ * // We'll use the 'customData' field to store metadata about the event
59
+ * customData: {eventId: '12345'},
60
+ *
61
+ * // We want the user clicking the notification to open the associated event, so register an 'onSelect' action
62
+ * onSelect: {task: 'view-calendar-event', target: 'popup'},
63
+ *
64
+ * buttons: [
65
+ * // A button that will schedule another reminder for 5 minutes from now. Since the application will be
66
+ * // responsible for snoozing the event, it will need to know about the user clicking this button. By setting
67
+ * // a NotificationActionResult for 'onClick', the service will raise a "notification-action" event when this
68
+ * // button is clicked, and will pass the value of 'onClick' as the 'result' field within the event
69
+ * {
70
+ * title: 'Snooze for 5 minutes',
71
+ * iconUrl: 'https://www.example.com/timer.png',
72
+ * onClick: {
73
+ * task: 'schedule-reminder',
74
+ * intervalMs: 5 * 60 * 1000
75
+ * }
76
+ * },
77
+ *
78
+ * // A button that closes the notification and doesn't prompt the user about this event again. Since the
79
+ * // application doesn't need to do anything when the user clicks this button, we leave 'onClick' undefined
80
+ * // rather than specifying a NotificationActionResult. This means that no action will be raised when the
81
+ * // button is clicked, and hence no "notification-action" event will be fired
82
+ * {
83
+ * title: 'Dismiss',
84
+ * iconUrl: 'https://www.example.com/cancel.png'
85
+ * }
86
+ * ]
87
+ * });
88
+ *
89
+ * // Create a listener that will be called for each action
90
+ * // Note: This handler will be used for ALL actions, from ALL notifications that are created by this application.
91
+ * addEventListener('notification-action', (event: NotificationActionEvent) => {
92
+ * const {result, notification} = event;
93
+ *
94
+ * if (result['task'] === 'view-calendar-event') {
95
+ * // Open a window with full details of the associated event
96
+ * openEventDetails(notification.customData.eventId, result['target']);
97
+ * } else if (result['task'] === 'schedule-reminder') {
98
+ * // Schedule a new notification
99
+ * scheduleReminder(notification.customData.eventId, Date.now() + result['intervalMs']);
100
+ * } // Etc...
101
+ * });
102
+ * ```
103
+ *
104
+ * The example above uses `customData` to store details about the notification subject (in this case, a calendar
105
+ * event), and `onClick` actions to inform the application about how it should respond when the user interacts with the
106
+ * notification. This is our intended usage and recommended best-practice, but the service doesn't require applications
107
+ * to follow this convention - application developers are free to decide how to manage notification state.
108
+ *
109
+ * Within the `notification-action` handler, the application must be able to understand which notification is being
110
+ * handled, and how to decide what it should do next. The example above uses an application-defined `action` field to
111
+ * determine the correct action, but the notification's `id`, `customData` and other fields are also useful
112
+ * selectors.
113
+ *
114
+ * @module Actions
115
+ */
116
+ /**
117
+ * Need a comment block here so that the comment block above is interpreted as a file comment, and not a comment on the
118
+ * import below.
119
+ *
120
+ * @hidden
121
+ */
122
+
123
+ /**
124
+ * Denotes a field as being an action. Defining this field (with a non-`undefined` value) will result in actions being
125
+ * raised and sent back to the source application when the corresponding event happens.
126
+ *
127
+ * For example, providing a value for the `onClick` field of {@link ButtonOptions} will result in a
128
+ * {@link NotificationActionEvent|`notification-action`} event being fired when that button is clicked.
129
+ *
130
+ * The `NotificationActionResult returned back to an application is static
131
+ * and must be defined at the point where the notification is created.
132
+ */
133
+ type ActionDeclaration<T extends never, E extends never> = NotificationActionResult;
134
+ /**
135
+ * Data type used to represent the action result returned back to applications when an action is raised. Applications
136
+ * capture these responses by adding a `notification-action` listener. The contents of this type are entirely
137
+ * application-defined, the only requirement is that the item is serializable by `JSON.stringify`.
138
+ *
139
+ * Since this type is entirely application-specific, the type is used in these definitions. However, there is an
140
+ * optional generic argument here, which can be used if an application were to define its own conventions for the shape
141
+ * of this field (which is recommended). To make use of this, define a `notification-action` handler that includes the
142
+ * application-defined type as a template argument. This type is then propagated up to {@link NotificationActionEvent}.
143
+ * The example below demonstrates this, using the same use-case as at the top of this page.
144
+ *
145
+ * ```ts
146
+ * interface MyAction = SnoozeAction | DetailsAction;
147
+ *
148
+ * interface SnoozeAction {
149
+ * task: 'schedule-reminder';
150
+ * intervalMs: number;
151
+ * }
152
+ *
153
+ * interface DetailsAction {
154
+ * task: 'view-calendar-event';
155
+ * target: 'self'|'popup';
156
+ * }
157
+ *
158
+ * addEventListener('notification-action', (event: NotificationActionEvent<MyAction>)) => {
159
+ * if (event.result.task === 'schedule-reminder') {
160
+ * // 'event.result' will now be strongly-typed as an instance of SnoozeAction
161
+ * scheduleReminder(notification.customData.eventId, Date.now() + result.intervalMs);
162
+ * }
163
+ * // Etc...
164
+ * };
165
+ * ```
166
+ */
167
+ type NotificationActionResult<T = CustomData> = T;
168
+ /**
169
+ * Lists the different triggers that can raise an {@link Actions|action}. Each action that is raised will result in a
170
+ * {@link NotificationActionEvent|`notification-action`} event, which can be captured by the application that created
171
+ * the notification.
172
+ */
173
+ declare enum ActionTrigger {
174
+ /**
175
+ * The user interacted with one of the controls in the notification: a button or an actionable fragment.
176
+ */
177
+ CONTROL = "control",
178
+ /**
179
+ * The user clicked the body of the notification itself. Any clicks of the notification that don't hit a control
180
+ * or the close button will fire an event with the `'select'` action trigger.
181
+ */
182
+ SELECT = "select",
183
+ /**
184
+ * The notification was closed, either by user interaction, programmatically by an application, or by the notification expiring.
185
+ */
186
+ CLOSE = "close",
187
+ /**
188
+ * The notification expired.
189
+ */
190
+ EXPIRE = "expire",
191
+ /**
192
+ * The action was triggered programmatically by an application.
193
+ *
194
+ * *Not currently supported*
195
+ */
196
+ PROGRAMMATIC = "programmatic"
197
+ }
198
+ /**
199
+ * Noop action types see {@link ActionNoop|ActionNoop}.
200
+ */
201
+ declare enum ActionNoopType {
202
+ /**
203
+ * No event will be raised and no dismissal of the notification on action.
204
+ */
205
+ EVENT_DISMISS = "event_dismiss"
206
+ }
207
+ /**
208
+ * BODY_CLICK action types see {@link ActionBodyClick|ActionBodyClick}.
209
+ */
210
+ declare enum ActionBodyClickType {
211
+ /**
212
+ * Dissmisal/Clearing event will be raised
213
+ */
214
+ DISMISS_EVENT = "dismiss_event"
215
+ }
216
+ /**
217
+ * @depracated {__NOOP__} has been deprecated. Notifications now default to not triggering the dismiss action when the body is clicked
218
+ *
219
+ * Setting the `__NOOP__` field on an action with a {@link ActionNoopType|type} allows you to override default user interaction with a notification.
220
+ *
221
+ * @example
222
+ * ```
223
+ * const notification = {
224
+ * //...
225
+ * onSelect: {__NOOP__: ActionNoopType.EVENT_DISMISS}
226
+ * };
227
+ * ```
228
+ *
229
+ * When a user clicks the notification body, the notification will not be dismissed and no event will be raised to the client application.
230
+ *
231
+ * <li> Currently <code>ActionBodyClickType.DISMISS_EVENT</code> is only supported by <code>ActionTrigger.SELECT/onSelect</code></li>
232
+ */
233
+ interface ActionNoop {
234
+ __NOOP__?: ActionNoopType;
235
+ }
236
+ /**
237
+ * Set the `BODY_CLICK` field on an action with a {@link ActionBodyClickType|type} to allow the end-user to click the body of the notification to dismiss it. This was the default behavior in earlier releases. An event is also sent to the client application.
238
+ *
239
+ * Note the following restrictions:
240
+ *
241
+ * <ul>
242
+ * <li>This override is ignored if buttons are passed to notification options.</li>
243
+ * <li>The <code>ActionBodyClickType.DISMISS_EVENT</code> is supported only by <code>ActionTrigger.SELECT/onSelect</code></li>
244
+ *
245
+ * @example
246
+ * ```
247
+ * const notification = {
248
+ * //...
249
+ * onSelect: {BODY_CLICK: ActionBodyClickType.DISMISS_EVENT}
250
+ * };
251
+ * ```
252
+ *
253
+ */
254
+ interface ActionBodyClick {
255
+ BODY_CLICK?: ActionBodyClickType;
256
+ }
257
+
258
+ type actions_d_ActionBodyClick = ActionBodyClick;
259
+ type actions_d_ActionBodyClickType = ActionBodyClickType;
260
+ declare const actions_d_ActionBodyClickType: typeof ActionBodyClickType;
261
+ type actions_d_ActionDeclaration<T extends never, E extends never> = ActionDeclaration<T, E>;
262
+ type actions_d_ActionNoop = ActionNoop;
263
+ type actions_d_ActionNoopType = ActionNoopType;
264
+ declare const actions_d_ActionNoopType: typeof ActionNoopType;
265
+ type actions_d_ActionTrigger = ActionTrigger;
266
+ declare const actions_d_ActionTrigger: typeof ActionTrigger;
267
+ type actions_d_NotificationActionResult<T = CustomData> = NotificationActionResult<T>;
268
+ declare namespace actions_d {
269
+ export { actions_d_ActionBodyClickType as ActionBodyClickType, actions_d_ActionNoopType as ActionNoopType, actions_d_ActionTrigger as ActionTrigger };
270
+ export type { actions_d_ActionBodyClick as ActionBodyClick, actions_d_ActionDeclaration as ActionDeclaration, actions_d_ActionNoop as ActionNoop, actions_d_NotificationActionResult as NotificationActionResult };
271
+ }
272
+
273
+ /**
274
+ * @module Notifications
275
+ */
276
+ /**
277
+ * @deprecated
278
+ * Lists possible semantic use-cases for notifications, which can alter how the notification is presented to the user.
279
+ */
280
+ declare enum IndicatorType {
281
+ FAILURE = "failure",
282
+ WARNING = "warning",
283
+ SUCCESS = "success"
284
+ }
285
+ /**
286
+ * Lists possible colors available for use as NotificationIndicator background color.
287
+ */
288
+ declare enum IndicatorColor {
289
+ RED = "red",
290
+ GREEN = "green",
291
+ YELLOW = "yellow",
292
+ BLUE = "blue",
293
+ PURPLE = "purple",
294
+ GRAY = "gray",
295
+ ORANGE = "orange",
296
+ MAGENTA = "magenta",
297
+ TEAL = "teal"
298
+ }
299
+ interface NotificationIndicator {
300
+ /**
301
+ * @deprecated
302
+ *
303
+ * Deprecated - use the priority field instead.
304
+ *
305
+ * Indicates the semantic intent behind the indicator - this determines the visual styling of the indicator when
306
+ * seen by the user.
307
+ *
308
+ * For example - an indicator could be used to:
309
+ * - `IndicatorType.FAILURE`: Indicate a failure has occurred from an action the user has taken.
310
+ * - `IndicatorType.WARNING`: Warn a user that they have a limited amount of time to buy.
311
+ * - `IndicatorType.SUCCESS`: Inform the user that an item has been successfully ordered.
312
+ */
313
+ type?: IndicatorType;
314
+ /**
315
+ * The indicator banner color. Defaults to red.
316
+ */
317
+ color?: IndicatorColor;
318
+ /**
319
+ * Customized text to be displayed in the indicator. When set, this will override the default indicator text.
320
+ * Text is limited to 32 characters including spaces.
321
+ */
322
+ text?: string;
323
+ }
324
+ interface NotificationIndicatorWithCustomColor extends Omit<NotificationIndicator, 'color'> {
325
+ /**
326
+ * Custom color string for indicator banner. This string must be defined in `theme` during Workspace Platform initialization.
327
+ */
328
+ color: string;
329
+ /**
330
+ * Fallback color if custom color could not be found in theme.
331
+ */
332
+ fallback: IndicatorColor;
333
+ }
334
+
335
+ /**
336
+ * These are available widgets for use in forms.
337
+ *
338
+ * @module FormWidgets
339
+ */
340
+ /**
341
+ * The StringWidgetType is how you display a text string.
342
+ */
343
+ declare const StringWidgetType: {
344
+ readonly Text: "Text";
345
+ readonly Dropdown: "Dropdown";
346
+ };
347
+ declare const NumberWidgetType: {
348
+ readonly Number: "Number";
349
+ };
350
+ declare const BooleanWidgetType: {
351
+ readonly Toggle: "Toggle";
352
+ readonly Checkbox: "Checkbox";
353
+ };
354
+ declare const CheckboxGroupWidgetType: {
355
+ readonly CheckboxGroup: "CheckboxGroup";
356
+ };
357
+ declare const RadioGroupWidgetType: {
358
+ readonly RadioGroup: "RadioGroup";
359
+ };
360
+ declare const DateWidgetType: {
361
+ readonly Date: "Date";
362
+ };
363
+ declare const TimeWidgetType: {
364
+ readonly Time: "Time";
365
+ };
366
+ declare const WidgetType: {
367
+ readonly Time: "Time";
368
+ readonly Date: "Date";
369
+ readonly RadioGroup: "RadioGroup";
370
+ readonly CheckboxGroup: "CheckboxGroup";
371
+ readonly Toggle: "Toggle";
372
+ readonly Checkbox: "Checkbox";
373
+ readonly Number: "Number";
374
+ readonly Text: "Text";
375
+ readonly Dropdown: "Dropdown";
376
+ };
377
+ /**
378
+ * All available widgets.
379
+ */
380
+ type Widget = StringWidget | NumberWidget | BooleanWidget | CheckboxGroupWidget | RadioGroupWidget | DateWidget;
381
+ interface BaseWidgetSpec<T extends keyof typeof WidgetType> {
382
+ /**
383
+ * The type of widget to be used. Widgets can only be used with matching specific data types.
384
+ * For example the `Text` widget can be used with the `string` field type.
385
+ */
386
+ type: T;
387
+ }
388
+ /**
389
+ * A simple text field input widget.
390
+ */
391
+ interface TextWidgetSpec extends BaseWidgetSpec<typeof WidgetType['Text']> {
392
+ placeholder?: string;
393
+ multiline?: boolean;
394
+ rows?: number;
395
+ }
396
+ /**
397
+ * String field input widget.
398
+ */
399
+ type StringWidget = TextWidgetSpec | DropdownWidgetSpec;
400
+ interface NumberWidgetSpec extends BaseWidgetSpec<typeof WidgetType['Number']> {
401
+ placeholder?: string;
402
+ min?: number;
403
+ max?: number;
404
+ currencyChar?: string;
405
+ decimalPlaces?: number;
406
+ step?: number;
407
+ }
408
+ interface CheckboxGroupWidgetSpec extends BaseWidgetSpec<typeof WidgetType['CheckboxGroup']> {
409
+ group: Array<{
410
+ value: string;
411
+ label: string;
412
+ }>;
413
+ }
414
+ type CheckboxGroupWidget = CheckboxGroupWidgetSpec;
415
+ interface RadioGroupWidgetSpec extends BaseWidgetSpec<typeof WidgetType['RadioGroup']> {
416
+ group: Array<{
417
+ value: string;
418
+ label: string;
419
+ }>;
420
+ }
421
+ type RadioGroupWidget = RadioGroupWidgetSpec;
422
+ interface DateWidgetSpec extends BaseWidgetSpec<typeof WidgetType['Date']> {
423
+ minDate?: Date | null;
424
+ maxDate?: Date | null;
425
+ }
426
+ type TimeWidgetSpec = BaseWidgetSpec<typeof WidgetType['Time']>;
427
+ type DateWidget = DateWidgetSpec;
428
+ type TimeWidget = TimeWidgetSpec;
429
+ interface DropdownWidgetSpec extends BaseWidgetSpec<typeof WidgetType['Dropdown']> {
430
+ placeholder?: string;
431
+ options: Array<{
432
+ value: string;
433
+ label: string;
434
+ }>;
435
+ }
436
+ type DropdownWidget = DropdownWidgetSpec;
437
+ /**
438
+ * Number field input widget.
439
+ */
440
+ type NumberWidget = NumberWidgetSpec;
441
+ type ToggleWidgetSpec = BaseWidgetSpec<typeof WidgetType['Toggle']>;
442
+ type CheckboxWidgetSpec = BaseWidgetSpec<typeof WidgetType['Checkbox']>;
443
+ type BooleanWidget = ToggleWidgetSpec | CheckboxWidgetSpec;
444
+
445
+ /**
446
+ * @module Provider
447
+ */
448
+ /**
449
+ * Status object returned by the Provider.
450
+ */
451
+ interface ProviderStatus {
452
+ /**
453
+ * The current connection status from the Client to the Provider.
454
+ */
455
+ connected: boolean;
456
+ /**
457
+ * The version number of the Provider. If the Provider is not connected, this will be `null`.
458
+ */
459
+ version: string | null;
460
+ /**
461
+ * The version number of the Templates API. If the Provider is not connected, this will be `null`.
462
+ */
463
+ templateAPIVersion?: string | null;
464
+ }
465
+ /**
466
+ * Retrieves the connection status and version semver of the Service Provider in the shape of a {@link ProviderStatus} object.
467
+ *
468
+ * If the Provider is connected, its' version number will be supplied in the returned object. If not, `version` will be `null`.
469
+ *
470
+ * ```ts
471
+ * import {provider} from 'openfin-notifications';
472
+ *
473
+ * const status: ProviderStatus = provider.getStatus();
474
+ * console.log(status.connected ? `Conencted to provider (version ${status.version})` : 'Not connected to provider');
475
+ * ```
476
+ *
477
+ * Note: Connection status is only available when the connected provider is verison 0.11.2 or later. For earlier
478
+ * versions, this API will indicate that the provider is disconnected.
479
+ *
480
+ * @since 0.11.2
481
+ *
482
+ * Note: Template API version is only available when the connected provider is verison 1.10.2 or later.
483
+ *
484
+ */
485
+ declare function getStatus(): Promise<ProviderStatus>;
486
+ /**
487
+ * Evaluates the provided version against the Providers version.
488
+ *
489
+ * This will return `true` if the Provider version is greater than or equal to the provided version. If not, `false` will be returned.
490
+ *
491
+ * If the Provider is not connected, `false` will be returned.
492
+ *
493
+ * ```ts
494
+ * import {provider, VERSION} from 'openfin-notifications';
495
+ *
496
+ * const hasMatchingProvider: boolean = provider.isConnectedToAtLeast(VERSION);
497
+ * if (!hasMatchingProvider) {
498
+ * console.warn('Connected to an older provider version. Some functionality may not be available.');
499
+ * }
500
+ * ```
501
+ *
502
+ * Note: Version information is only available when the connected provider is verison 0.11.2 or later. For earlier
503
+ * versions, this API will indicate that the provider is disconnected.
504
+ *
505
+ * @param version Version to compare against the Provider version. This should be in semvar format.
506
+ * @since 0.11.2
507
+ */
508
+ declare function isConnectedToAtLeast(version: string): Promise<boolean>;
509
+
510
+ type provider_d_ProviderStatus = ProviderStatus;
511
+ declare const provider_d_getStatus: typeof getStatus;
512
+ declare const provider_d_isConnectedToAtLeast: typeof isConnectedToAtLeast;
513
+ declare namespace provider_d {
514
+ export { provider_d_getStatus as getStatus, provider_d_isConnectedToAtLeast as isConnectedToAtLeast };
515
+ export type { provider_d_ProviderStatus as ProviderStatus };
516
+ }
517
+
518
+ /**
519
+ * @hidden
520
+ */
521
+ /**
522
+ * Need a comment block here so that the comment block above is interpreted as a file comment, and not a comment on the
523
+ * import below.
524
+ *
525
+ * @hidden
526
+ */
527
+ /**
528
+ * For notifications that have originated from an application running on the same machine as the provider.
529
+ */
530
+ interface NotificationSourceDesktop {
531
+ type: 'desktop';
532
+ /**
533
+ * The identity of the window that raised this notification.
534
+ *
535
+ * This will always be a window of the current application - but
536
+ * could have been raised by an instance of this application
537
+ * running on a different machine.
538
+ */
539
+ identity: OpenFin.Identity;
540
+ /**
541
+ * The origin of the notification, which is the url of the window that raised the notification.
542
+ * This property is optional to support backward compatibility with sources that do not have the origin starting with version 2.7.1.
543
+ */
544
+ origin?: string;
545
+ }
546
+ /**
547
+ * Union of all possible notification sources.
548
+ */
549
+ type NotificationSource = NotificationSourceDesktop;
550
+
551
+ /**
552
+ * @hidden
553
+ */
554
+ /**
555
+ * File contains types used to communicate between client and provider.
556
+ *
557
+ * These types are a part of the client, but are not required by applications wishing to interact with the service.
558
+ * This file is excluded from the public-facing TypeScript documentation.
559
+ */
560
+
561
+ type ColorSchemeOption = ColorSchemeType;
562
+ /**
563
+ * Distribute Omit across all union types instead of Omitting the union.
564
+ * https://davidgomes.com/pick-omit-over-union-types-in-typescript/
565
+ */
566
+ type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;
567
+ type MakePropertyRequired<T, Prop extends keyof T> = Omit<T, Prop> & Required<Pick<T, Prop>>;
568
+
569
+ /**
570
+ * When you make a form, you provide a list of [[FormFields]]. Each FormField contains the ingredients to make a single widget in the form.
571
+ * The actual definitions of the widgets are derived from [[BaseWidgetSpec]].
572
+ *
573
+ * A FormField contains the type of data, the key to store the user input into [[CustomDataWithForms]], and some additional configuration.
574
+ * @module FormFields
575
+ */
576
+ /**
577
+ * imports.
578
+ */
579
+
580
+ /**
581
+ * Data type of a fields. e.g. string, number
582
+ */
583
+ declare const FieldType: {
584
+ readonly string: "string";
585
+ readonly number: "number";
586
+ readonly boolean: "boolean";
587
+ readonly date: "date";
588
+ readonly checkboxGroup: "checkboxGroup";
589
+ readonly radioGroup: "radioGroup";
590
+ readonly time: "time";
591
+ };
592
+ /**
593
+ * An abstract validation entry.
594
+ */
595
+ interface ValidationEntry<T = any> {
596
+ /**
597
+ * Message displayed to the user when input is invalid.
598
+ */
599
+ invalidMessage?: string;
600
+ /**
601
+ * Validation argument to test against.
602
+ */
603
+ arg?: T;
604
+ }
605
+ /**
606
+ * The base type for form fields.
607
+ */
608
+ interface BaseField<T extends keyof typeof FieldType, D = unknown> {
609
+ /**
610
+ * Field data type.
611
+ */
612
+ type: T;
613
+ /**
614
+ * The property key that this field value will appear in the returned {@link NotificationFormSubmittedEvent.form|form} object.
615
+ */
616
+ key: string;
617
+ /**
618
+ * Default value for field, and where it will be written to
619
+ */
620
+ value?: D;
621
+ /**
622
+ * Validation rules used to validate user input.
623
+ */
624
+ validation?: Record<string, any>;
625
+ /**
626
+ * Input label.
627
+ */
628
+ label?: string;
629
+ /**
630
+ * Helper text.
631
+ */
632
+ helperText?: string;
633
+ }
634
+ /**
635
+ * String field within a form.
636
+ */
637
+ interface StringField<W extends StringWidget = StringWidget> extends BaseField<'string', string> {
638
+ validation?: Partial<{
639
+ /**
640
+ * Minimum number of characters.
641
+ */
642
+ min: ValidationEntry<number>;
643
+ /**
644
+ * Maximum number of characters.
645
+ */
646
+ max: ValidationEntry<number>;
647
+ /**
648
+ * Length of the input string.
649
+ */
650
+ length: ValidationEntry<number>;
651
+ /**
652
+ * The field is required to be filled in by the user.
653
+ */
654
+ required: ValidationEntry;
655
+ /**
656
+ * Provide a regex string that will be tested against the input value.
657
+ */
658
+ match: ValidationEntry<string>;
659
+ }>;
660
+ /**
661
+ * What input widget is used.
662
+ * @default StringWidgets {@link StringWidgets}
663
+ */
664
+ widget: W;
665
+ }
666
+ /**
667
+ * Number field within a form.
668
+ */
669
+ interface NumberField<W extends NumberWidget = NumberWidget> extends BaseField<'number', number> {
670
+ validation?: Partial<{
671
+ /**
672
+ * Minimum number of characters.
673
+ */
674
+ min: ValidationEntry<number>;
675
+ /**
676
+ * Maximum number of characters.
677
+ */
678
+ max: ValidationEntry<number>;
679
+ /**
680
+ * Number must be less than this.
681
+ */
682
+ lessThan: ValidationEntry<number>;
683
+ /**
684
+ * Number must be more than this.
685
+ */
686
+ moreThan: ValidationEntry<number>;
687
+ /**
688
+ * Number must be positive.
689
+ */
690
+ positive: ValidationEntry;
691
+ /**
692
+ * Number must be negative.
693
+ */
694
+ negative: ValidationEntry;
695
+ /**
696
+ * The field is required to be filled in by the user.
697
+ */
698
+ required: ValidationEntry;
699
+ }>;
700
+ widget: W;
701
+ }
702
+ interface BooleanField<W extends BooleanWidget = BooleanWidget> extends BaseField<'boolean', boolean> {
703
+ widget: W;
704
+ }
705
+ type DateFieldValue = {
706
+ date?: number;
707
+ month?: number;
708
+ year?: number;
709
+ };
710
+ interface DateField<W extends DateWidget = DateWidget> extends BaseField<'date', DateFieldValue> {
711
+ widget: W;
712
+ }
713
+ type TimeFieldValue = {
714
+ hour?: number;
715
+ minute?: number;
716
+ };
717
+ interface TimeField<W extends TimeWidget = TimeWidget> extends BaseField<'time', TimeFieldValue> {
718
+ widget: W;
719
+ }
720
+ interface RadioGroupField<W extends RadioGroupWidget = RadioGroupWidget> extends BaseField<'radioGroup', string> {
721
+ widget: W;
722
+ }
723
+ interface CheckboxGroupField<W extends CheckboxGroupWidget = CheckboxGroupWidget> extends BaseField<'checkboxGroup', Array<string>> {
724
+ widget: W;
725
+ }
726
+ /**
727
+ * A field in a form.
728
+ */
729
+ type FormField = StringField | NumberField | BooleanField | DateField | RadioGroupField | CheckboxGroupField | TimeField;
730
+ /**
731
+ * A field in a form.
732
+ *
733
+ * The difference with [[FormField]] is that the label property is required.
734
+ */
735
+ type FormFieldWithRequiredLabel = MakePropertyRequired<FormField, 'label'>;
736
+ /**
737
+ * A field in a form. Either [[FormField]] or [[FormFieldWithRequiredLabel]]
738
+ */
739
+ type AnyFormField = FormField | FormFieldWithRequiredLabel;
740
+ /**
741
+ * An ordered array of fields representing a form.
742
+ * When the form is displayed to the user the fields will appear in the same order they are in the array.
743
+ */
744
+ type NotificationFormData = ReadonlyArray<FormField>;
745
+ /**
746
+ * An ordered array of fields representing a form.
747
+ * When the form is displayed to the user the fields will appear in the same order they are in the array.
748
+ *
749
+ * The difference with [[NotificationFormData]] is that the label property is required for each field.
750
+ */
751
+ type NotificationFormDataWithRequiredLabel = ReadonlyArray<FormFieldWithRequiredLabel>;
752
+
753
+ type FormStatus = 'not-submitted' | 'submitting' | 'submitted';
754
+ interface FormStatusOptions {
755
+ /**
756
+ * Controls form status,
757
+ */
758
+ formStatus: FormStatus;
759
+ /**
760
+ * Sets error message at the top of the form.
761
+ */
762
+ error?: string;
763
+ _notificationId: string;
764
+ }
765
+ type CustomValidationError = {
766
+ fieldKey: string;
767
+ error: string;
768
+ };
769
+
770
+ /**
771
+ * OpenFin Notification Templates API Version 1
772
+ *
773
+ * @module Templates
774
+ */
775
+ /**
776
+ * imports
777
+ */
778
+
779
+ type SectionAlignment = 'left' | 'center' | 'right';
780
+ type ListPairs = [string, string][];
781
+ type CustomTemplateData = Record<string, string | ListPairs>;
782
+ /**
783
+ * The options you pass to the [[create]] function to generate a notification.
784
+ */
785
+ type NotificationOptions = TemplateMarkdown | TemplateList | TemplateCustom;
786
+ /**
787
+ * The options to build your custom template composition layout.
788
+ */
789
+ type TemplateFragment = ContainerTemplateFragment | TextTemplateFragment | ListTemplateFragment | ImageTemplateFragment | ActionableTextTemplateFragment;
790
+ declare const TemplateNames: {
791
+ readonly markdown: "markdown";
792
+ readonly list: "list";
793
+ readonly custom: "custom";
794
+ };
795
+ declare const ContainerTemplateFragmentNames: {
796
+ readonly container: "container";
797
+ };
798
+ declare const PresentationTemplateFragmentNames: {
799
+ readonly text: "text";
800
+ readonly image: "image";
801
+ readonly list: "list";
802
+ readonly actionableText: "actionableText";
803
+ };
804
+ declare const TemplateFragmentNames: {
805
+ readonly text: "text";
806
+ readonly image: "image";
807
+ readonly list: "list";
808
+ readonly actionableText: "actionableText";
809
+ readonly container: "container";
810
+ };
811
+ interface TemplateComposition {
812
+ /**
813
+ * Minimum Template API version required for the service to render this composition.
814
+ *
815
+ * For example, a composition that consists only of container, text, image, or list
816
+ * fragments must declare a minimum template API version of "1".
817
+ *
818
+ * See {@link BodyTemplateOptions} for more details.
819
+ */
820
+ minTemplateAPIVersion: string;
821
+ /**
822
+ * Root of the template composition tree. See {@link ContainerTemplateFragment} for nesting.
823
+ */
824
+ layout: TemplateFragment;
825
+ }
826
+ interface IndicatorTemplateOptions {
827
+ /**
828
+ * Alignment of the notification's indicator section.
829
+ *
830
+ * Can be `left`, `center` or `right`.
831
+ *
832
+ * The default value is `center`.
833
+ */
834
+ align?: SectionAlignment;
835
+ /**
836
+ * Color of the indicator bar.
837
+ *
838
+ * Note: {@link BaseNotificationOptions|Notification's indicator color} definition has precedence over Template definition.
839
+ * Template's indicator color value will be taken into account only if the notification itself doesn't have the indicator color
840
+ * specified.
841
+ */
842
+ color?: IndicatorColor;
843
+ }
844
+ interface ButtonTemplateOptions {
845
+ /**
846
+ * Alignment of the notification's button section.
847
+ *
848
+ * Can be `left`, `center` or `right`.
849
+ *
850
+ * The default value is `right`.
851
+ */
852
+ align?: SectionAlignment;
853
+ }
854
+ interface BodyTemplateOptions {
855
+ /**
856
+ * A list of template compositions.
857
+ *
858
+ * You can include multiple compositions with different minimum Template API version to create fallback compositions and support the
859
+ * earlier versions of Notification Center (Starting from the Template API version 1).
860
+ *
861
+ * The service will search for the composition with the version number matching the Template API version it is supporting.
862
+ * If this doesn't exist, the service will then select the composition with the nearest version number smaller than the Template API version
863
+ * it is supporting and render the notification card with that composition.
864
+ */
865
+ compositions: TemplateComposition[];
866
+ /**
867
+ * Composition fallback text.
868
+ *
869
+ * The service will render this text instead of the notification body section if there are no compatible compositions found in the template.
870
+ *
871
+ * (E.g. All of the compositions in the template declare a greater minimum Template API version than the version supported by the running
872
+ * service instance.)
873
+ *
874
+ */
875
+ fallbackText?: string;
876
+ }
877
+ interface BaseTemplateFragment<T extends keyof typeof TemplateFragmentNames> {
878
+ /**
879
+ * Type of the template fragment.
880
+ */
881
+ type: T;
882
+ /**
883
+ * CSS style properties of the fragment.
884
+ *
885
+ * All the available custom template fragments support all of the React's inline style properties (with camelCase keys)
886
+ *
887
+ * Note: "position: fixed" is disallowed in the fragments.
888
+ */
889
+ style?: Record<string, string | number>;
890
+ }
891
+ interface ContainerTemplateFragment extends BaseTemplateFragment<'container'>, ActionableFragment {
892
+ /**
893
+ * Sub-fragments of the container.
894
+ *
895
+ * You can use container template fragment to create nested composition structures.
896
+ */
897
+ children?: TemplateFragment[];
898
+ }
899
+ interface PresentationTemplateFragment<T extends keyof typeof PresentationTemplateFragmentNames> extends BaseTemplateFragment<T> {
900
+ /**
901
+ * Optional flag.
902
+ *
903
+ * If a presentation template fragment is flagged as optional, The service will not require
904
+ * the fragment's `dataKey` to exist in `templateData`. If a fragment is optional and its data
905
+ * is missing, the fragment will be omitted quietly by the server.
906
+ */
907
+ optional?: boolean;
908
+ /**
909
+ * Data key of the template fragment.
910
+ *
911
+ * The data associated with this fragment will be looked up in `templateData` map with this key.
912
+ *
913
+ * Example:
914
+ * ```ts
915
+ * const myTemplate = {
916
+ * body: {
917
+ * compositions: [{
918
+ * minTemplateAPIVersion: '1',
919
+ * layout: {
920
+ * type: CustomTemplateFragmentNames.text,
921
+ * dataKey: 'message',
922
+ * },
923
+ * }],
924
+ * },
925
+ * }
926
+ *
927
+ * const notificationOption: TemplateCustom = {
928
+ * //...
929
+ * templateOptions: myTemplate,
930
+ * templateData: {
931
+ * message: 'My Custom Notification Message',
932
+ * }
933
+ * };
934
+ * ```
935
+ *
936
+ */
937
+ dataKey: string;
938
+ }
939
+ interface ActionableFragment {
940
+ /**
941
+ * onClick object that is user defined.
942
+ *
943
+ * If provided, notification-action event will be raised when clicking on the fragment.
944
+ *
945
+ *
946
+ * Example:
947
+ * ```ts
948
+ * {
949
+ * "type": "actionableText",
950
+ * "dataKey": "titlexyz",
951
+ * "tooltipKey": "some_key",
952
+ * "onClick": { // contents are user-defined
953
+ * "task": "schedule-reminder",
954
+ * "eventId": 142341,
955
+ * "intervalMs": 5000
956
+ * }
957
+ * }
958
+ *
959
+ * import { addEventListener, clear } from 'openfin-notifications';
960
+ *
961
+ * addEventListener('notification-action', (event: NotificationActionEvent<MyAction>)) => {
962
+ * if (event.result.task === 'schedule-reminder') {
963
+ * scheduleReminder(event.result.eventId, Date.now() + event.result.intervalMs);
964
+ * }
965
+ * clear(event.notification.id);
966
+ * });
967
+ * ```
968
+ *
969
+ */
970
+ onClick?: ActionDeclaration<never, never> | null;
971
+ /**
972
+ * Tooltip key of the template fragment.
973
+ *
974
+ * The string tooltip associated with this fragment will be looked up in templateData map with this key.
975
+ *
976
+ *
977
+ * Example:
978
+ * ```ts
979
+ * const myTemplate = {
980
+ * body: {
981
+ * compositions: [{
982
+ * minTemplateAPIVersion: '1',
983
+ * layout: {
984
+ * type: "actionableText",
985
+ * dataKey: 'message',
986
+ * tooltipKey: 'tooltipxyz',
987
+ * },
988
+ * }],
989
+ * },
990
+ * }
991
+ *
992
+ * const notificationOption: TemplateCustom = {
993
+ * //...
994
+ * templateOptions: myTemplate,
995
+ * templateData: {
996
+ * message: 'view stock tracker',
997
+ * tooltipxyz: 'My Custom Tooltip',
998
+ * }
999
+ * };
1000
+ * ```
1001
+ *
1002
+ */
1003
+ tooltipKey?: string;
1004
+ }
1005
+ type TextTemplateFragment = PresentationTemplateFragment<'text'>;
1006
+ type ImageTemplateFragment = PresentationTemplateFragment<'image'> & ActionableFragment;
1007
+ type ListTemplateFragment = PresentationTemplateFragment<'list'>;
1008
+ type ActionableTextTemplateFragment = PresentationTemplateFragment<'actionableText'> & ActionableFragment;
1009
+ /**
1010
+ * Configuration options for the custom notification template.
1011
+ */
1012
+ interface CustomTemplateOptions {
1013
+ /**
1014
+ * Configuration options for the custom notification template body.
1015
+ */
1016
+ body: BodyTemplateOptions;
1017
+ /**
1018
+ * Configuration options for the custom notification template's modifications on the notification's indicator section.
1019
+ */
1020
+ indicator?: IndicatorTemplateOptions;
1021
+ /**
1022
+ * Configuration options for the custom notification template's modifications on the notification's button section.
1023
+ */
1024
+ buttons?: ButtonTemplateOptions;
1025
+ }
1026
+ /**
1027
+ * Default markdown template. Contains a markdown body and forms data.
1028
+ */
1029
+ interface TemplateMarkdown extends Omit<BaseNotificationOptions<'markdown'>, 'template'> {
1030
+ template?: 'markdown';
1031
+ /**
1032
+ * Notification body text.
1033
+ *
1034
+ * This is the main notification content, displayed below the notification title. The notification will expand to fit the length of this text.
1035
+ * Markdown may be used in the body text to control how it is styled when rendered.
1036
+ * With the exception of links and code blocks, all basic syntax as documented [here](https://www.markdownguide.org/basic-syntax) is supported.
1037
+ */
1038
+ body: string;
1039
+ /**
1040
+ * A collection of form fields or a form definition (Form<FormField>)
1041
+ * @example
1042
+ * ```ts
1043
+ * [
1044
+ * {
1045
+ * key: 'phone',
1046
+ * type: 'string',
1047
+ * label: 'Phone',
1048
+ * helperText:
1049
+ * 'Must be in the following formats 123-456-7890, 123 456 7890, (123) 456 7890 or 1234567890',
1050
+ * widget: {
1051
+ * type: 'Text'
1052
+ * },
1053
+ * validation: {
1054
+ * required: {
1055
+ * arg: true
1056
+ * }
1057
+ * }
1058
+ * },
1059
+ * {
1060
+ * key: 'email',
1061
+ * type: 'string',
1062
+ * label: 'Email',
1063
+ * helperText: 'We will use this email to send you the report after we crawl your website',
1064
+ * widget: {
1065
+ * type: 'Text'
1066
+ * },
1067
+ * validation: {
1068
+ * required: {
1069
+ * arg: true
1070
+ * }
1071
+ * }
1072
+ * }
1073
+ * ]
1074
+ * ```
1075
+ */
1076
+ form?: NotificationFormData | Form<FormField> | null;
1077
+ }
1078
+ /**
1079
+ * Simple template that can render a list of name-value pairs.
1080
+ */
1081
+ interface TemplateList extends BaseNotificationOptions<'list'> {
1082
+ /**
1083
+ * Notification list template data.
1084
+ */
1085
+ list: Record<string, string>;
1086
+ }
1087
+ /**
1088
+ * Notification that renders custom templates.
1089
+ */
1090
+ interface TemplateCustom extends BaseNotificationOptions<'custom'> {
1091
+ templateOptions: CustomTemplateOptions;
1092
+ /**
1093
+ * Data associated with the custom notification template's presentation fragments.
1094
+ */
1095
+ templateData: CustomTemplateData;
1096
+ /**
1097
+ * A collection of form fields or a form definition (Form<FormField>)
1098
+ * @example
1099
+ * ```ts
1100
+ * [
1101
+ * {
1102
+ * key: 'phone',
1103
+ * type: 'string',
1104
+ * label: 'Phone',
1105
+ * helperText:
1106
+ * 'Must be in the following formats 123-456-7890, 123 456 7890, (123) 456 7890 or 1234567890',
1107
+ * widget: {
1108
+ * type: 'Text'
1109
+ * },
1110
+ * validation: {
1111
+ * required: {
1112
+ * arg: true
1113
+ * }
1114
+ * }
1115
+ * },
1116
+ * {
1117
+ * key: 'email',
1118
+ * type: 'string',
1119
+ * label: 'Email',
1120
+ * helperText: 'We will use this email to send you the report after we crawl your website',
1121
+ * widget: {
1122
+ * type: 'Text'
1123
+ * },
1124
+ * validation: {
1125
+ * required: {
1126
+ * arg: true
1127
+ * }
1128
+ * }
1129
+ * }
1130
+ * ]
1131
+ * ```
1132
+ */
1133
+ form?: NotificationFormDataWithRequiredLabel | Form<FormFieldWithRequiredLabel> | null;
1134
+ }
1135
+ interface FormSettings {
1136
+ /**
1137
+ * Controls that display of (Required) or (Optional) labels next to form fields.
1138
+ */
1139
+ displayFieldRequirementStatus?: boolean;
1140
+ }
1141
+ interface Form<T extends FormField | FormFieldWithRequiredLabel> extends FormSettings {
1142
+ /**
1143
+ * A collection of form fields.
1144
+ * @example
1145
+ * ```ts
1146
+ * [
1147
+ * {
1148
+ * key: 'phone',
1149
+ * type: 'string',
1150
+ * label: 'Phone',
1151
+ * helperText:
1152
+ * 'Must be in the following formats 123-456-7890, 123 456 7890, (123) 456 7890 or 1234567890',
1153
+ * widget: {
1154
+ * type: 'Text'
1155
+ * },
1156
+ * validation: {
1157
+ * required: {
1158
+ * arg: true
1159
+ * }
1160
+ * }
1161
+ * },
1162
+ * {
1163
+ * key: 'email',
1164
+ * type: 'string',
1165
+ * label: 'Email',
1166
+ * helperText: 'We will use this email to send you the report after we crawl your website',
1167
+ * widget: {
1168
+ * type: 'Text'
1169
+ * },
1170
+ * validation: {
1171
+ * required: {
1172
+ * arg: true
1173
+ * }
1174
+ * }
1175
+ * }
1176
+ * ]
1177
+ * ```
1178
+ */
1179
+ fields: ReadonlyArray<T>;
1180
+ }
1181
+
1182
+ /**
1183
+ * Core notification features.
1184
+ *
1185
+ * @module BaseNotificationOptions
1186
+ */
1187
+ /**
1188
+ * imports
1189
+ */
1190
+
1191
+ /**
1192
+ * Configuration options for constructing a Notifications object, shared between all templates.
1193
+ */
1194
+ interface BaseNotificationOptions<T extends keyof typeof TemplateNames> {
1195
+ /**
1196
+ * A unique identifier for the notification.
1197
+ *
1198
+ * If not provided at time of creation, one will be generated for you and returned as part of the {@link create} method.
1199
+ */
1200
+ id?: string;
1201
+ /**
1202
+ * Template of the notification payload.
1203
+ */
1204
+ template: T;
1205
+ /**
1206
+ * Title of the notification.
1207
+ *
1208
+ * Displayed as the first line of the notification, in a heading style.
1209
+ */
1210
+ title: string;
1211
+ /**
1212
+ * If set to false, the user won't be able to set a reminder for this notification in the Notification Center.
1213
+ *
1214
+ * Default value is `true`.
1215
+ */
1216
+ allowReminder?: boolean;
1217
+ /**
1218
+ * Describes the context of this notification. Allows users to control different notification types that are raised
1219
+ * by an application.
1220
+ *
1221
+ * This string is not displayed on the notification itself, but should be user-readable. It will be displayed in
1222
+ * the Notification Center preferences section, and any string passed as a `category` should make sense when
1223
+ * displayed in that context.
1224
+ *
1225
+ * Event categories should list all the different types of notifications raised by your app. As a general guide, if
1226
+ * a user may want to have different preferences for some subset of notifications created by your app, then
1227
+ * applications should ensure that those notifications have a distinct category.
1228
+ *
1229
+ * @deprecated This property is deprecated and will be removed in a future release.
1230
+ */
1231
+ category?: string;
1232
+ /**
1233
+ * Add a semantic visual indicator to a notification, to signal to the user the nature of the event that they are
1234
+ * being notified about.
1235
+ *
1236
+ * This should not be treated as a priority.
1237
+ */
1238
+ indicator?: NotificationIndicator | NotificationIndicatorWithCustomColor | null;
1239
+ /**
1240
+ * URL of the icon to be displayed in the notification.
1241
+ */
1242
+ icon?: string;
1243
+ /**
1244
+ * Application-defined context data that can be attached to buttons on notifications.
1245
+ *
1246
+ * When using forms, form data submitted will be written to `customData` and returned to your app by
1247
+ * listening to the submit {@link NotificationActionEvent|`notification-action`} with the trigger {@link ActionTrigger.SUBMIT|submit}.
1248
+ */
1249
+ customData?: CustomData;
1250
+ /**
1251
+ * The timestamp shown on the notification. If omitted, the current date/time will be used.
1252
+ *
1253
+ * This is presentational only - a date in the future does not incur a scheduling action.
1254
+ */
1255
+ date?: Date;
1256
+ /**
1257
+ * The expiry date and time of the notification. If specified, the notification will be removed at this time, or as
1258
+ * soon as possible after. If not specified, the notification will never expire, and will persist until it
1259
+ * is closed.
1260
+ */
1261
+ expires?: Date | null;
1262
+ /**
1263
+ * When set to `sticky` this settings enables the notification toast to stay visible on the desktop
1264
+ * until the user interacts with it. When set to `transient` the toasts will follow the default behavior
1265
+ * of fading away after a short duration. When set to `none` the toasts will not appear and the notification
1266
+ * will only appear in the Notification Center.
1267
+ *
1268
+ * This property has a precedence over `sticky` propery.
1269
+ *
1270
+ */
1271
+ toast?: 'sticky' | 'transient' | 'none';
1272
+ /**
1273
+ * @deprecated
1274
+ *
1275
+ * This property is deprecated. Use `toast` instead.
1276
+ */
1277
+ sticky?: 'sticky' | 'transient';
1278
+ /**
1279
+ * A list of buttons to display below the notification text.
1280
+ *
1281
+ * Notifications support up to four buttons. Attempting to add more than four will result in the notification
1282
+ * being rejected by the service.
1283
+ */
1284
+ buttons?: ButtonOptions[];
1285
+ /**
1286
+ * Notification Stream
1287
+ *
1288
+ * If the notification belongs to a stream, the user will be able to group notifications by stream.
1289
+ */
1290
+ stream?: NotificationStream | null;
1291
+ /**
1292
+ * Id of the platform this notification belongs to.
1293
+ *
1294
+ * If the application belongs to a platform, the user interaction with the notification will be dispatched
1295
+ * back to the platform provider.
1296
+ */
1297
+ platform?: string | null;
1298
+ /**
1299
+ * An {@link NotificationActionResult|action result} to be passed back to the application inside the
1300
+ * {@link NotificationActionEvent|`notification-action`} event fired when the notification is clicked.
1301
+ *
1302
+ * This action will only be raised on clicks to the notification body. Interactions with buttons (both
1303
+ * application-defined buttons, and the default 'X' close button) or with actionable fragments will not trigger a
1304
+ * {@link ActionTrigger.SELECT|select} action.
1305
+ *
1306
+ * See {@link Actions} for more details on notification actions, and receiving action events from notifications.
1307
+ */
1308
+ onSelect?: (ActionDeclaration<never, never> & ActionNoop & ActionBodyClick) | null;
1309
+ /**
1310
+ * An {@link NotificationActionResult|action result} to be passed back to the application inside the
1311
+ * {@link NotificationActionEvent|`notification-action`} event fired when the notification the expires.
1312
+ *
1313
+ * If `expires` is specified for the notification, this action will be raised when the notification expires. If
1314
+ * `expires` is not specified for the notification, this action will never be raised. Note that if an `onClose`
1315
+ * action result is also specified, both actions will be raised if and when the notification expires.
1316
+ *
1317
+ * See {@link Actions} for more details on notification actions, and receiving action events from notifications.
1318
+ */
1319
+ onExpire?: ActionDeclaration<never, never> | null;
1320
+ /**
1321
+ * An {@link NotificationActionResult|action result} to be passed back to the application inside the
1322
+ * {@link NotificationActionEvent|`notification-action`} event fired when the notification is closed.
1323
+ *
1324
+ * This action is raised regardless of how the notification is closed, whether from user interaction, expiration,
1325
+ * or programmatic removal -- such as a call to `clear`.
1326
+ *
1327
+ * See {@link Actions} for more details on notification actions, and receiving action events from notifications.
1328
+ */
1329
+ onClose?: ActionDeclaration<never, never> | null;
1330
+ /**
1331
+ * A priority for this notification. It's from 1 - 4.
1332
+ */
1333
+ priority?: number;
1334
+ /**
1335
+ * Sound options for a notification.
1336
+ */
1337
+ soundOptions?: NotificationSoundOptions;
1338
+ }
1339
+
1340
+ /**
1341
+ * Configuration options for constructing an updatable Notifications object, shared between all templates.
1342
+ */
1343
+ interface BaseUpdatableNotificationOptions<T extends keyof typeof TemplateNames> {
1344
+ /**
1345
+ * A unique identifier for the notification.
1346
+ *
1347
+ * Mandatory field for Notification updates.
1348
+ */
1349
+ id: string;
1350
+ /**
1351
+ * description of update type 'markdown', 'list' or 'custom'
1352
+ */
1353
+ template?: T;
1354
+ /**
1355
+ * Application-defined context data that can be attached to buttons on notifications.
1356
+ *
1357
+ * When using forms, form data submitted will be written to `customData` and returned to your app by
1358
+ * listening to the submit {@link NotificationActionEvent|`notification-action`} with the trigger {@link ActionTrigger.SUBMIT|submit}.
1359
+ */
1360
+ customData?: CustomData;
1361
+ /**
1362
+ * A list of buttons to display below the notification text.
1363
+ *
1364
+ * Notifications support up to four buttons. Attempting to add more than four will result in the notification
1365
+ * being rejected by the service.
1366
+ */
1367
+ buttons?: ButtonOptions[];
1368
+ }
1369
+
1370
+ /**
1371
+ * Default markdown template update.
1372
+ */
1373
+ interface UpdatableNotificationTemplateMarkdown extends Omit<BaseUpdatableNotificationOptions<'markdown'>, 'template'> {
1374
+ template?: 'markdown';
1375
+ body?: string;
1376
+ form?: NotificationFormData | null;
1377
+ }
1378
+ /**
1379
+ * Simple template that can render a list of name-value pairs.
1380
+ */
1381
+ interface UpdatableNotificationTemplateList extends BaseUpdatableNotificationOptions<'list'> {
1382
+ /**
1383
+ * Notification list template data.
1384
+ */
1385
+ list?: Record<string, string>;
1386
+ }
1387
+ /**
1388
+ * Update Payload for Custom Template Notification.
1389
+ * This will let you update the template data associated with the existing template
1390
+ * composition of the notification template.
1391
+ */
1392
+ interface UpdatableNotificationTemplateCustom extends BaseUpdatableNotificationOptions<'custom'> {
1393
+ /**
1394
+ * Data associated with the custom notification template's presentation fragments.
1395
+ */
1396
+ templateData?: CustomTemplateData;
1397
+ form?: NotificationFormData | null;
1398
+ }
1399
+ type UpdatableNotificationOptions = UpdatableNotificationTemplateMarkdown | UpdatableNotificationTemplateList | UpdatableNotificationTemplateCustom;
1400
+
1401
+ /**
1402
+ * Notifications allow additional UI components to be specified by applications. The service controls the
1403
+ * positioning and styling of these components.
1404
+ *
1405
+ * @module Controls
1406
+ */
1407
+ /**
1408
+ * Need a comment block here so that the comment block above is interpreted as a file comment, and not a comment on the
1409
+ * import below.
1410
+ *
1411
+ * @hidden
1412
+ */
1413
+
1414
+ /**
1415
+ * Helper to make the `type` field required on any type that defines it as being optional.
1416
+ */
1417
+ type WithExplicitType<T extends {
1418
+ type?: string;
1419
+ }> = T & {
1420
+ type: string;
1421
+ };
1422
+ /**
1423
+ * *Not yet implemented*
1424
+ *
1425
+ * Union of the options objects of all "primary control" components supported by the service.
1426
+ */
1427
+ type PrimaryControlOptions = never;
1428
+ /**
1429
+ * Union of options objects of all components that can be added to a notification, includes both buttons and primary
1430
+ * controls.
1431
+ */
1432
+ type ControlOptions = Required<PrimaryControlOptions | WithExplicitType<ButtonOptions>> | WithExplicitType<ActionableTextTemplateFragment> | WithExplicitType<ImageTemplateFragment> | WithExplicitType<ContainerTemplateFragment>;
1433
+ /**
1434
+ * Configuration options for constructing a button within a notification.
1435
+ */
1436
+ interface ButtonOptions {
1437
+ /**
1438
+ * The type of the control. Optional, added automatically if `NotificationOptions.buttons` includes the `onClick`
1439
+ * property and therefore generates a `notification-action` event.
1440
+ */
1441
+ type?: 'button';
1442
+ /**
1443
+ * User-facing button text.
1444
+ *
1445
+ * The button caption should be kept short, particularly if there are multiple buttons. Notifications are
1446
+ * fixed-width, and all buttons will be displayed on the same row.
1447
+ */
1448
+ title: string;
1449
+ /**
1450
+ * Indicates that this button will be visually displayed as a 'Call to Action' button. In this case a Call To Action
1451
+ * means the button is made more prominent. We recommend you use this for true calls to action. For example, if you
1452
+ * have a notification which contains a report, it might have an 'OK' button which takes you to the report, and a
1453
+ * 'Dismiss' button which simply closes the notification. We suggest you make only the 'OK' button a CTA here.'
1454
+ *
1455
+ * If set as `false` or `undefined`, the default simple text button will be used instead.
1456
+ */
1457
+ cta?: boolean;
1458
+ /**
1459
+ * Indicates that this button should submit a form.
1460
+ * If a form is invalid, based on your validation rules provided, the button will be disabled until the users input within the form is valid.
1461
+ */
1462
+ submit?: boolean;
1463
+ /**
1464
+ * @deprecated
1465
+ * Optional icon URL, if an icon should be placed on the button.
1466
+ *
1467
+ * Icons are placed to the left of the button text.
1468
+ */
1469
+ iconUrl?: string;
1470
+ /**
1471
+ * Defines the data to be passed back to the application when the button is clicked.
1472
+ *
1473
+ * The {@link NotificationActionResult} specified here will be returned to the application via a
1474
+ * `notification-action` event when the button is clicked.
1475
+ *
1476
+ * If omitted or `null`, applications will not receive a {@link NotificationActionEvent|`notification-action`}
1477
+ * event when the button is clicked. This may be appropriate if the button represents a "dismiss" or some other
1478
+ * side-effect-free interaction. Even if `onClick` is omitted or `null`, a `notification-closed` event will still be
1479
+ * raised after the button click.
1480
+ *
1481
+ */
1482
+ onClick?: ActionDeclaration<never, never> | null;
1483
+ /**
1484
+ * Button index used for events. This gets set when hydrating.
1485
+ *
1486
+ * @hidden
1487
+ */
1488
+ index?: number;
1489
+ formOptions?: {
1490
+ /**
1491
+ * Title to display on a button when form is submitting.
1492
+ */
1493
+ submittingTitle?: string | null;
1494
+ /**
1495
+ * Title to display on a button when form is in the error state.
1496
+ */
1497
+ errorTitle?: string | null;
1498
+ /**
1499
+ * Title to display on a button when form is in the success state.
1500
+ */
1501
+ successTitle?: string | null;
1502
+ } | null;
1503
+ }
1504
+
1505
+ /**
1506
+ * @module Notifications
1507
+ */
1508
+ /**
1509
+ * Sound options for a notification
1510
+ */
1511
+ interface NotificationSoundOptions {
1512
+ /**
1513
+ * Determines the sound that will be played when a notification is received.
1514
+ *
1515
+ * @default 'default' plays the default notification sound.
1516
+ */
1517
+ mode: 'default' | 'silent';
1518
+ }
1519
+
1520
+ /**
1521
+ * @module Notifications
1522
+ */
1523
+ /**
1524
+ * Details of the application that will handle any actions coming from a particular stream.
1525
+ */
1526
+ interface NotificationStream {
1527
+ /**
1528
+ * Unique id of the stream.
1529
+ */
1530
+ id: string;
1531
+ /**
1532
+ * Stream title.
1533
+ *
1534
+ * Providing a different displayName for an existing stream id will update the
1535
+ * displayName of the stream stored in Notification Center.
1536
+ *
1537
+ */
1538
+ displayName: string;
1539
+ /**
1540
+ * ID of the application source of this stream.
1541
+ */
1542
+ appId: string;
1543
+ }
1544
+
1545
+ interface NotificationsThemeSet extends ThemeSet {
1546
+ light: ThemeExtension;
1547
+ dark: ThemeExtension;
1548
+ }
1549
+ interface ThemeExtension extends DefaultTheme {
1550
+ notificationIndicatorColors?: Record<string, NotificationIndicatorColorsSet>;
1551
+ }
1552
+ interface NotificationIndicatorColorsSet {
1553
+ background: string;
1554
+ foreground: string;
1555
+ }
1556
+ declare module 'styled-components' {
1557
+ interface DefaultTheme {
1558
+ notificationIndicatorColors?: Record<string, NotificationIndicatorColorsSet>;
1559
+ }
1560
+ }
1561
+
1562
+ interface NotificationsPlatform {
1563
+ /**
1564
+ * Unique identifier of the platform.
1565
+ */
1566
+ id: string;
1567
+ /**
1568
+ * Stream title.
1569
+ *
1570
+ * Providing a different displayName for an existing stream id will update the
1571
+ * displayName of the stream stored in Notification Center.
1572
+ *
1573
+ */
1574
+ title: string;
1575
+ /**
1576
+ * URL of the icon to be displayed for this platform.
1577
+ */
1578
+ icon: string;
1579
+ /**
1580
+ * This is the theme associated with this platform. The center will be themed accordingly
1581
+ * when the platform is selected.
1582
+ */
1583
+ theme?: NotificationsThemeSet;
1584
+ /**
1585
+ * This is the scheme associated with this platform.
1586
+ */
1587
+ scheme?: ColorSchemeOption;
1588
+ /**
1589
+ * Workspace platform that registers this platform
1590
+ */
1591
+ workspacePlatform?: {
1592
+ /**
1593
+ * @deprecated
1594
+ */
1595
+ identity: OpenFin.ApplicationIdentity;
1596
+ analytics: {
1597
+ isSupported: boolean;
1598
+ };
1599
+ };
1600
+ platformIdentity: OpenFin.ApplicationIdentity;
1601
+ }
1602
+ type PlatformRegisterPayload<T extends NotificationsPlatform = NotificationsPlatform> = Omit<T, 'platformIdentity'>;
1603
+ interface PlatformDeregisterPayload {
1604
+ id: string;
1605
+ }
1606
+
1607
+ /**
1608
+ * @module NotificationCenter
1609
+ */
1610
+ /**
1611
+ * Need a comment block here so that the comment block above is interpreted as a file comment, and not a comment on the
1612
+ * import below.
1613
+ *
1614
+ * @hidden
1615
+ */
1616
+
1617
+ /**
1618
+ * The Notification Client library's version in semver format.
1619
+ *
1620
+ * This is the version which you are currently using.
1621
+ */
1622
+ declare const VERSION: string;
1623
+ /**
1624
+ * Application-defined context data that can be attached to buttons on notifications.
1625
+ */
1626
+ type CustomData = Record<string, any>;
1627
+ /**
1628
+ * A fully-hydrated form of {@link NotificationOptions}.
1629
+ *
1630
+ * After {@link create|creating} a notification, the service will return an object of this type. This will be the given
1631
+ * options object, with any unspecified fields filled-in with default values.
1632
+ *
1633
+ * This object should be treated as immutable. Modifying its state will not have any effect on the notification or the
1634
+ * state of the service.
1635
+ */
1636
+ type Notification<T extends NotificationOptions = NotificationOptions> = Readonly<Required<DistributiveOmit<T, 'buttons'>> & {
1637
+ readonly buttons: ReadonlyArray<Required<ButtonOptions>>;
1638
+ }>;
1639
+ type UpdatableNotification<T extends UpdatableNotificationOptions = UpdatableNotificationOptions> = Readonly<DistributiveOmit<T, 'buttons'> & {
1640
+ readonly buttons?: ReadonlyArray<Required<ButtonOptions>>;
1641
+ }>;
1642
+ /**
1643
+ * Event fired when an action is raised for a notification due to a specified trigger. It is important to note that
1644
+ * applications will only receive these events if they indicate to the service that they want to receive these events.
1645
+ * See {@link actions} for a full example of how actions are defined, and how an application can listen to and handle
1646
+ * them.
1647
+ *
1648
+ * This can be fired due to interaction with notification buttons or the notification itself, the notification being
1649
+ * closed (either by user interaction or by API call), or by the notification expiring. Later versions of the service
1650
+ * will add additional control types that may raise actions from user interaction. All actions, for all control types,
1651
+ * will be returned to the application via the same `notification-action` event type.
1652
+ *
1653
+ * The event object will contain the application-defined {@link NotificationActionResult|metadata} that allowed this
1654
+ * action to be raised, and details on what triggered this action and which control the user interacted with.
1655
+ *
1656
+ * Unlike other event types, `notification-action` events will be buffered by the service until the application has
1657
+ * added a listener for this event type, at which point it will receive all buffered `notification-action` events. The
1658
+ * service will also attempt to restart the application if it is not running when the event is fired.
1659
+ *
1660
+ * This type includes a generic type argument, should applications wish to define their own interface for action
1661
+ * results. See {@link NotificationActionResult} for details.
1662
+ *
1663
+ * @event "notification-action"
1664
+ */
1665
+ interface NotificationActionEvent<T = CustomData> {
1666
+ type: 'notification-action';
1667
+ /**
1668
+ * The notification that created this action
1669
+ */
1670
+ notification: Readonly<Notification>;
1671
+ /**
1672
+ * This property allows the application handling the action to identify where this notification originated.
1673
+ */
1674
+ source: NotificationSource;
1675
+ /**
1676
+ * Indicates what triggered this action.
1677
+ *
1678
+ * Note that the `programmatic` trigger is not yet implemented.
1679
+ */
1680
+ trigger: ActionTrigger;
1681
+ /**
1682
+ * The control whose interaction resulted in this action being raised. Will only be present when {@link trigger} is
1683
+ * {@link ActionTrigger.CONTROL}.
1684
+ *
1685
+ * Future versions of the service will add additional controls beyond buttons, and interactions with these new
1686
+ * control types will also come through this one event type. For best forward-compatibility, applications should
1687
+ * always check the `type` property of this control, and not assume that the type will always be `'button'`.
1688
+ *
1689
+ * This field is marked optional as future versions of the service will also include alternate methods of raising
1690
+ * `notification-action` events that do not originate from a button or other control.
1691
+ *
1692
+ * When present, the object here will always be strictly equal to one of the control definitions within
1693
+ * `notification`. This means `indexOf` checks and other equality checks can be performed on this field if
1694
+ * required, such as:
1695
+ *
1696
+ * ```ts
1697
+ * function onNotificationAction(event: NotificationActionEvent): void {
1698
+ * if (event.control && event.control.type === 'button') {
1699
+ * const butttonIndex = event.notification.buttons.indexOf(event.control);
1700
+ *
1701
+ * // Handle button click
1702
+ * // . . .
1703
+ * }
1704
+ * }
1705
+ * ```
1706
+ */
1707
+ control?: Readonly<ControlOptions>;
1708
+ /**
1709
+ * Application-defined metadata that this event is passing back to the application.
1710
+ *
1711
+ * A `notification-action` event is only fired for a given trigger if the
1712
+ * {@link NotificationOptions|notification options} included an action result for that trigger.
1713
+ *
1714
+ * See the comment on the {@link NotificationActionEvent} type for an example of buttons that do and don't raise
1715
+ * actions.
1716
+ */
1717
+ result: NotificationActionResult<T>;
1718
+ }
1719
+ /**
1720
+ * Event fired whenever notification toast has been dismissed. This could be either by pressing notification dismiss `-` button or
1721
+ * by clicking notification body if BODY_CLICK action has been set to "dismiss_event".
1722
+ *
1723
+ * @event "notification-toast-dismissed"
1724
+ */
1725
+ interface NotificationToastDismissedEvent {
1726
+ type: 'notification-toast-dismissed';
1727
+ notification: Notification;
1728
+ }
1729
+ /**
1730
+ * Event fired whenever the notification has been closed.
1731
+ *
1732
+ * This event is fired regardless of how the notification was closed - i.e.: via a call to `clear`/`clearAll`, the
1733
+ * notification expiring, or by a user clicking either the notification itself, the notification's close button, or
1734
+ * a button on the notification.
1735
+ *
1736
+ * @event "notification-closed"
1737
+ */
1738
+ interface NotificationClosedEvent {
1739
+ type: 'notification-closed';
1740
+ /**
1741
+ * The notification that has just been closed.
1742
+ *
1743
+ * This object will match what is returned from the `create` call when the notification was first created.
1744
+ */
1745
+ notification: Notification;
1746
+ }
1747
+ /**
1748
+ * Event fired whenever a new notification has been created.
1749
+ *
1750
+ * @event "notification-created"
1751
+ */
1752
+ interface NotificationCreatedEvent {
1753
+ type: 'notification-created';
1754
+ /**
1755
+ * The notification that has just been created.
1756
+ *
1757
+ * This object will match what is returned from the `create` call.
1758
+ */
1759
+ notification: Notification;
1760
+ }
1761
+ /**
1762
+ * Event fired whenever a reminder has been created either via the Notifications API
1763
+ * or by the user on the Notification Center UI
1764
+ *
1765
+ * @event "notification-reminder-created"
1766
+ */
1767
+ interface NotificationReminderCreatedEvent {
1768
+ type: 'notification-reminder-created';
1769
+ /**
1770
+ * The reminder notification that has just been created.
1771
+ *
1772
+ * This object will match what is returned from the `create` call when the notification
1773
+ * was first created.
1774
+ */
1775
+ notification: Notification;
1776
+ /**
1777
+ * The reminder time-out timestamp.
1778
+ */
1779
+ reminderDate: Date;
1780
+ }
1781
+ /**
1782
+ * Event fired whenever a reminder has been canceled by the user, reminder notification is deleted or the reminder timeout has reached.
1783
+ *
1784
+ * @event "notification-reminder-removed"
1785
+ */
1786
+ interface NotificationReminderRemovedEvent {
1787
+ type: 'notification-reminder-removed';
1788
+ /**
1789
+ * The notification associated with the reminder that has just been removed.
1790
+ *
1791
+ * This object will match what is returned from the `create` call when the notification was first created.
1792
+ */
1793
+ notification: Notification;
1794
+ }
1795
+ /**
1796
+ * Event fired whenever the total number of notifications from **all** sources changes.
1797
+ *
1798
+ * @event "notifications-count-changed"
1799
+ */
1800
+ interface NotificationsCountChanged {
1801
+ type: 'notifications-count-changed';
1802
+ /**
1803
+ * Number of notifications in the Center.
1804
+ */
1805
+ count: number;
1806
+ }
1807
+ /**
1808
+ * Event fired whenever any of the notification form fields changes.
1809
+ *
1810
+ * @event "notification-form-value-changed"
1811
+ */
1812
+ interface NotificationFormValuesChangedEvent {
1813
+ type: 'notification-form-values-changed';
1814
+ notification: Notification;
1815
+ form: Record<string, unknown>;
1816
+ /**
1817
+ * Allows to set validation errors for the form fields.
1818
+ * If validation errors are set, the submit button will be disabled.
1819
+ * @param validationErrors
1820
+ * Array of objects with fieldKey and error properties.
1821
+ * @returns
1822
+ * Promise that resolves when the validation errors are set.
1823
+ *
1824
+ * @example
1825
+ * addEventListener(
1826
+ * 'notification-form-values-changed',
1827
+ * async (formValueChanged: NotificationFormValuesChangedEvent) => {
1828
+ * const errors = [];
1829
+ *
1830
+ * // Simpler regular expression to test for a valid HTTP or HTTPS URL
1831
+ * const phonePattern = /^\(?([0-9]{3})\)?[- ]?([0-9]{3})[- ]?([0-9]{4})$/;
1832
+ *
1833
+ * // Simpler regular expression to test for a valid email address
1834
+ * const emailPattern = /^\S+@\S+\.\S+$/;
1835
+ *
1836
+ * // Fields to validate
1837
+ * const sourcePhone = formValueChanged.form.sourcePhone as string;
1838
+ * const email = formValueChanged.form.sourceEmail as string;
1839
+ *
1840
+ * // Validate sourceUrl if it's not null or undefined
1841
+ * if (sourcePhone && !phonePattern.test(sourcePhone)) {
1842
+ * errors.push({
1843
+ * fieldKey: 'sourcePhone',
1844
+ * error: 'Invalid phone format'
1845
+ * });
1846
+ * }
1847
+ *
1848
+ * // Validate email if it's not null or undefined
1849
+ * if (email && !emailPattern.test(email)) {
1850
+ * errors.push({
1851
+ * fieldKey: 'sourceEmail',
1852
+ * error: 'Invalid email format'
1853
+ * });
1854
+ * }
1855
+ *
1856
+ * // If there are any errors, set them all at once
1857
+ * if (errors.length > 0) {
1858
+ * await formValueChanged.setErrors(errors);
1859
+ * }
1860
+ * }
1861
+ * );
1862
+ */
1863
+ setErrors: (validationErrors: Array<CustomValidationError>) => Promise<void>;
1864
+ }
1865
+ /**
1866
+ * Event fired whenever submit button is clicked on a notification form.
1867
+ *
1868
+ * @event "notification-form-submitted"
1869
+ */
1870
+ interface NotificationFormSubmittedEvent {
1871
+ type: 'notification-form-submitted';
1872
+ notification: Notification;
1873
+ button: ButtonOptions;
1874
+ form: Record<string, unknown>;
1875
+ /**
1876
+ * Prevents the default behaviour of notification form submit, where notification card gets dismissed right after submit.
1877
+ *
1878
+ * @example
1879
+ * addEventListener('notification-form-submitted', async (event) => {
1880
+ * // preventing the default submit behaviour
1881
+ * event.preventDefault();
1882
+ *
1883
+ * // setting the form status to processing
1884
+ * event.setFormStatus({
1885
+ * formStatus: 'Processing'
1886
+ * });
1887
+ *
1888
+ * const longOperationResult = await ...();
1889
+ *
1890
+ * if (longOperationResult.hasError) {
1891
+ * // setting error if long-running operation has failed.
1892
+ * event.setFormStatus({
1893
+ * formStatus: 'not-submitted',
1894
+ * error: longOperationResult.operationErrorMessage
1895
+ * });
1896
+ * } else {
1897
+ * // setting form status to submitted
1898
+ * event.setFormStatus({
1899
+ * formStatus: 'submitted'
1900
+ * });
1901
+ * }
1902
+ * });
1903
+ */
1904
+ preventDefault: () => void;
1905
+ /**
1906
+ *
1907
+ * @param formStatusOptions
1908
+ * Allows to set the status of the form. The form status reflects the state of the submit button which includes its text.
1909
+ * Submit button text for different statuses is defined using `formOptions` property for a submit button when creating a notification.
1910
+ *
1911
+ * @example
1912
+ * addEventListener('notification-form-submitted', async (event) => {
1913
+ * // preventing the default submit behaviour
1914
+ * event.preventDefault();
1915
+ *
1916
+ * // setting the form status to processing
1917
+ * event.setFormStatus({
1918
+ * formStatus: 'Processing'
1919
+ * });
1920
+ *
1921
+ * const longOperationResult = await ...();
1922
+ *
1923
+ * if (longOperationResult.hasError) {
1924
+ * // setting error if long-running operation has failed.
1925
+ * event.setFormStatus({
1926
+ * formStatus: 'not-submitted',
1927
+ * error: longOperationResult.operationErrorMessage
1928
+ * });
1929
+ * } else {
1930
+ * // setting form status to submitted
1931
+ * event.setFormStatus({
1932
+ * formStatus: 'submitted'
1933
+ * });
1934
+ * }
1935
+ * });
1936
+ */
1937
+ setFormStatus: (formStatusOptions: Omit<FormStatusOptions, '_notificationId'>) => Promise<void>;
1938
+ }
1939
+ /**
1940
+ * Event fired whenever the Notification Sound Enabled setting is toggled in Notification Center.
1941
+ *
1942
+ * @event "notification-sound-toggled"
1943
+ */
1944
+ interface ToggleNotificationSound {
1945
+ type: 'notification-sound-toggled';
1946
+ notificationSoundEnabled: boolean;
1947
+ }
1948
+ declare function addEventListener(eventType: 'notification-form-values-changed', listener: (event: NotificationFormValuesChangedEvent) => void): void;
1949
+ declare function addEventListener(eventType: 'notification-form-submitted', listener: (event: NotificationFormSubmittedEvent) => void): Promise<void>;
1950
+ declare function addEventListener(eventType: 'notification-action', listener: (event: NotificationActionEvent) => void): Promise<void>;
1951
+ declare function addEventListener(eventType: 'notification-created', listener: (event: NotificationCreatedEvent) => void): Promise<void>;
1952
+ declare function addEventListener(eventType: 'notification-toast-dismissed', listener: (event: NotificationToastDismissedEvent) => void): Promise<void>;
1953
+ declare function addEventListener(eventType: 'notification-closed', listener: (event: NotificationClosedEvent) => void): Promise<void>;
1954
+ declare function addEventListener(eventType: 'notifications-count-changed', listener: (event: NotificationsCountChanged) => void): Promise<void>;
1955
+ declare function addEventListener(eventType: 'notification-reminder-created', listener: (event: NotificationReminderCreatedEvent) => void): Promise<void>;
1956
+ declare function addEventListener(eventType: 'notification-reminder-removed', listener: (event: NotificationReminderRemovedEvent) => void): Promise<void>;
1957
+ declare function addEventListener(eventType: 'notification-sound-toggled', listener: (event: ToggleNotificationSound) => void): Promise<void>;
1958
+ declare function removeEventListener(eventType: 'notification-form-submitted', listener: (event: NotificationFormSubmittedEvent) => void): Promise<void>;
1959
+ declare function removeEventListener(eventType: 'notification-action', listener: (event: NotificationActionEvent) => void): Promise<void>;
1960
+ declare function removeEventListener(eventType: 'notification-created', listener: (event: NotificationCreatedEvent) => void): Promise<void>;
1961
+ declare function removeEventListener(eventType: 'notification-toast-dismissed', listener: (event: NotificationToastDismissedEvent) => void): Promise<void>;
1962
+ declare function removeEventListener(eventType: 'notification-closed', listener: (event: NotificationClosedEvent) => void): Promise<void>;
1963
+ declare function removeEventListener(eventType: 'notifications-count-changed', listener: (event: NotificationsCountChanged) => void): Promise<void>;
1964
+ declare function removeEventListener(eventType: 'notification-reminder-created', listener: (event: NotificationReminderCreatedEvent) => void): Promise<void>;
1965
+ declare function removeEventListener(eventType: 'notification-reminder-removed', listener: (event: NotificationReminderRemovedEvent) => void): Promise<void>;
1966
+ declare function removeEventListener(eventType: 'notification-form-values-changed', listener: (event: NotificationFormValuesChangedEvent) => void): void;
1967
+ declare function removeEventListener(eventType: 'notification-sound-toggled', listener: (event: ToggleNotificationSound) => void): Promise<void>;
1968
+ /**
1969
+ * Extended configuration options for the notification creation.
1970
+ */
1971
+ interface NotificationCreationOptions {
1972
+ /**
1973
+ * The date on which the notification will be removed from reminders category and recreated
1974
+ * created as regular notification.
1975
+ *
1976
+ * If this date is earlier than the notification creation time, the notification will be created
1977
+ * immediately.
1978
+ * Cannot be earlier than the expiry date, if set.
1979
+ *
1980
+ */
1981
+ reminderDate?: Date;
1982
+ }
1983
+ /**
1984
+ * Creates a new notification.
1985
+ *
1986
+ * If a reminder is not set, the notification will immediately appear in the Notification Center and as a toast if the Center is not visible.
1987
+ * If a reminder is set, the notification will appear in the Center when the reminder date is reached.
1988
+ *
1989
+ * If a notification is created with an `id` of an already existing notification, the existing notification will be recreated with the new content.
1990
+ *
1991
+ * ```ts
1992
+ * import {create} from 'openfin-notifications';
1993
+ *
1994
+ * create({
1995
+ * id: 'uniqueNotificationId',
1996
+ * title: 'Notification Title',
1997
+ * body: 'Text to display within the notification body',
1998
+ * icon: 'https://openfin.co/favicon.ico'
1999
+ * }, {
2000
+ * reminderDate: new Date('October 21, 2015 07:28:00');
2001
+ * });
2002
+ * ```
2003
+ *
2004
+ * @param options Notification configuration options.
2005
+ * @param creationOptions Extended configuration options for the notification creation.
2006
+ */
2007
+ declare function create<T extends NotificationOptions>(options: T, creationOptions?: NotificationCreationOptions): Promise<Notification<T>>;
2008
+ /**
2009
+ * Updates an existing notification. Requires id of original Notification and one of:
2010
+ * - buttons
2011
+ * - customData
2012
+ * - Template
2013
+ *
2014
+ * The updated Notification will then show in Notification Centre and in the Toast stack if not expired.
2015
+ *
2016
+ * Example:
2017
+ * ```ts
2018
+ * import {update} from 'openfin-notifications';
2019
+ *
2020
+ * update({
2021
+ * id: uniqueNotificationId,
2022
+ * body: 'i am an update! - ' + Date.now().toString(),
2023
+ * template: 'markdown',
2024
+ * });
2025
+ * ```
2026
+ * @param options
2027
+ * @returns
2028
+ */
2029
+ declare function update<T extends UpdatableNotificationOptions>(options: T): Promise<Notification>;
2030
+ /**
2031
+ * Clears a specific notification from the Notification Center.
2032
+ *
2033
+ * Returns true if the notification was successfully cleared. Returns false if the notification was not cleared, without errors.
2034
+ *
2035
+ * ```ts
2036
+ * import {clear} from 'openfin-notifications';
2037
+ *
2038
+ * clear('uniqueNotificationId');
2039
+ * ```
2040
+ *
2041
+ * @param id ID of the notification to clear.
2042
+ */
2043
+ declare function clear(id: string): Promise<boolean>;
2044
+ /**
2045
+ * Retrieves all Notifications which were created by the calling application, including child windows.
2046
+ * Child window notifications will only be included if the notification security rules allow it.
2047
+ *
2048
+ * ```ts
2049
+ * import {getAll} from 'openfin-notifications'
2050
+ *
2051
+ * getAll().then((notifications: Notification[]) => {
2052
+ * console.log(`Service has ${notifications.length} notifications for this app:`, notifications);
2053
+ * });
2054
+ * ```
2055
+ *
2056
+ * There is deliberately no mechanism provided for fetching notifications that were created by a different application.
2057
+ */
2058
+ declare function getAll(): Promise<Notification[]>;
2059
+ /**
2060
+ * Clears all Notifications which were created by the calling application, including child windows.
2061
+ * Child window notifications will only be cleared if the notification security rules allow it.
2062
+ *
2063
+ * Returns the number of successfully cleared Notifications.
2064
+ *
2065
+ * ```ts
2066
+ * import {clearAll} from 'openfin-notifications';
2067
+ *
2068
+ * clearAll();
2069
+ * ```
2070
+ */
2071
+ declare function clearAll(): Promise<number>;
2072
+ /**
2073
+ * Toggles the visibility of the Notification Center.
2074
+ *
2075
+ * ```ts
2076
+ * import {toggleNotificationCenter} from 'openfin-notifications';
2077
+ *
2078
+ * toggleNotificationCenter();
2079
+ * ```
2080
+ */
2081
+ declare function toggleNotificationCenter(): Promise<void>;
2082
+ declare function setDefaultPlatformShortcut(shortcut: string): Promise<void>;
2083
+ /**
2084
+ * Options to modify the Notification Center behaviour when show() API is called.
2085
+ */
2086
+ interface ShowOptions {
2087
+ navigateToAll?: boolean;
2088
+ }
2089
+ /**
2090
+ * Sets the visibility of the Notification Center to true.
2091
+ *
2092
+ * ```ts
2093
+ * import { show } from 'openfin-notifications';
2094
+ *
2095
+ * show({ navigateToAll: false });
2096
+ * ```
2097
+ * @param showOptions
2098
+ */
2099
+ declare function show(options?: ShowOptions): Promise<void>;
2100
+ /**
2101
+ * Sets the visibility of the Notification Center to false.
2102
+ *
2103
+ * ```ts
2104
+ * import { hide } from 'openfin-notifications';
2105
+ *
2106
+ * hide();
2107
+ * ```
2108
+ */
2109
+ declare function hide(): Promise<void>;
2110
+ /**
2111
+ * Get the total count of notifications from **all** applications.
2112
+ *
2113
+ * ```ts
2114
+ * import {getNotificationsCount} from 'openfin-notifications';
2115
+ *
2116
+ * getNotificationsCount();
2117
+ * ```
2118
+ */
2119
+ declare function getNotificationsCount(): Promise<number>;
2120
+ declare const enum UserSettings {
2121
+ SOUND_ENABLED = "soundEnabled"
2122
+ }
2123
+ type UserSettingStatus = {
2124
+ [UserSettings.SOUND_ENABLED]: boolean;
2125
+ };
2126
+ /**
2127
+ * Retrieves a user setting from Notifications Center
2128
+ *
2129
+ * ```ts
2130
+ * import { getUserSettingStatus } from 'openfin-notifications';
2131
+ *
2132
+ * getUserSettingStatus('soundEnabled');
2133
+ * ```
2134
+ * @param UserSettings the setting of which you want to retrieve the current status.
2135
+ *
2136
+ * @returns
2137
+ * Promise that resolves to the status of the setting.
2138
+ */
2139
+ declare function getUserSettingStatus<T extends UserSettings>(setting: UserSettings): Promise<UserSettingStatus[T]>;
2140
+ /**
2141
+ * Set the allowedOrigins for the specific client that calls the function.
2142
+ *
2143
+ * ```ts
2144
+ * import { setAllowedOrigins } from 'openfin-notifications';
2145
+ *
2146
+ * setAllowedOrigins(['https://*.example.com']);
2147
+ * ```
2148
+ * @param allowedOrigins An array of allowed origins.
2149
+ */
2150
+ declare const setAllowedOrigins: (allowedOrigins: string[]) => Promise<void>;
2151
+
2152
+ type NotificationProviderConfig = NotificationProviderInfo & {
2153
+ /**
2154
+ * Unique identifier for the Notification Center instance.
2155
+ * Must be a non-empty string that matches the `serviceId` used in the Web Notification Center instance.
2156
+ */
2157
+ serviceId: string;
2158
+ /**
2159
+ * `fin` entry point for the Here Core Web.
2160
+ * For setup instructions, see: https://www.npmjs.com/package/@openfin/core-web
2161
+ */
2162
+ finContext: OpenFin.Fin<'external connection'>;
2163
+ };
2164
+ declare function connectToNotifications(config: NotificationProviderConfig): Promise<void>;
2165
+
2166
+ export { ActionBodyClickType, ActionNoopType, ActionTrigger, BooleanWidgetType, CheckboxGroupWidgetType, ContainerTemplateFragmentNames, DateWidgetType, FieldType, IndicatorColor, IndicatorType as NotificationIndicatorType, NumberWidgetType, PresentationTemplateFragmentNames, RadioGroupWidgetType, StringWidgetType, TemplateFragmentNames, TemplateNames, TimeWidgetType, UserSettings, VERSION, WidgetType, actions_d as actions, addEventListener, clear, clearAll, connectToNotifications, create, getAll, getNotificationsCount, getUserSettingStatus, hide, provider_d as provider, removeEventListener, setAllowedOrigins, setDefaultPlatformShortcut, show, toggleNotificationCenter, update };
2167
+ export type { ActionBodyClick, ActionDeclaration, ActionNoop, ActionableFragment, ActionableTextTemplateFragment, AnyFormField, BaseField, BaseNotificationOptions, BaseTemplateFragment, BaseUpdatableNotificationOptions, BaseWidgetSpec, BodyTemplateOptions, BooleanField, BooleanWidget, ButtonOptions, ButtonTemplateOptions, CheckboxGroupField, CheckboxGroupWidget, CheckboxGroupWidgetSpec, CheckboxWidgetSpec, ContainerTemplateFragment, ControlOptions, CustomData, CustomTemplateData, CustomTemplateOptions, CustomValidationError, DateField, DateFieldValue, DateWidget, DateWidgetSpec, DropdownWidget, DropdownWidgetSpec, Form, FormField, FormFieldWithRequiredLabel, FormSettings, FormStatus, FormStatusOptions, ImageTemplateFragment, IndicatorTemplateOptions, ListPairs, ListTemplateFragment, Notification, NotificationActionEvent, NotificationActionResult, NotificationClosedEvent, NotificationCreatedEvent, NotificationCreationOptions, NotificationFormData, NotificationFormDataWithRequiredLabel, NotificationFormSubmittedEvent, NotificationFormValuesChangedEvent, NotificationIndicator, NotificationIndicatorWithCustomColor, NotificationOptions, NotificationProviderConfig, NotificationReminderCreatedEvent, NotificationReminderRemovedEvent, NotificationSoundOptions, NotificationSource, NotificationSourceDesktop, NotificationStream, NotificationToastDismissedEvent, NotificationsCountChanged, NumberField, NumberWidget, NumberWidgetSpec, PlatformDeregisterPayload, PlatformRegisterPayload, PresentationTemplateFragment, PrimaryControlOptions, RadioGroupField, RadioGroupWidget, RadioGroupWidgetSpec, SectionAlignment, ShowOptions, StringField, StringWidget, TemplateComposition, TemplateCustom, TemplateFragment, TemplateList, TemplateMarkdown, TextTemplateFragment, TextWidgetSpec, TimeField, TimeFieldValue, TimeWidget, TimeWidgetSpec, ToggleNotificationSound, ToggleWidgetSpec, UpdatableNotification, UpdatableNotificationOptions, UpdatableNotificationTemplateCustom, UpdatableNotificationTemplateList, UpdatableNotificationTemplateMarkdown, UserSettingStatus, ValidationEntry, Widget };