diff --git a/docs/designers-developers/developers/data/data-core-notices.md b/docs/designers-developers/developers/data/data-core-notices.md index bb8d4c0e140818..5721292549b704 100644 --- a/docs/designers-developers/developers/data/data-core-notices.md +++ b/docs/designers-developers/developers/data/data-core-notices.md @@ -39,7 +39,7 @@ _Related_ _Parameters_ - _content_ `string`: Notice message. -- _options_ `?Object`: Optional notice options. +- _options_ `[Object]`: Optional notice options. _Returns_ @@ -57,7 +57,7 @@ _Related_ _Parameters_ - _content_ `string`: Notice message. -- _options_ `?Object`: Optional notice options. +- _options_ `[Object]`: Optional notice options. _Returns_ @@ -69,14 +69,15 @@ Yields action objects used in signalling that a notice is to be created. _Parameters_ -- _status_ `?string`: Notice status. Defaults to `info`. +- _status_ `[string]`: Notice status. - _content_ `string`: Notice message. -- _options_ `?Object`: Notice options. -- _options.context_ `?string`: Context under which to group notice. -- _options.id_ `?string`: Identifier for notice. Automatically assigned if not specified. -- _options.isDismissible_ `?boolean`: Whether the notice can be dismissed by user. Defaults to `true`. -- _options.speak_ `?boolean`: Whether the notice content should be announced to screen readers. Defaults to `true`. -- _options.actions_ `?Array`: User actions to be presented with notice. +- _options_ `[Object]`: Notice options. +- _options.context_ `[string]`: Context under which to group notice. +- _options.id_ `[string]`: Identifier for notice. Automatically assigned if not specified. +- _options.isDismissible_ `[boolean]`: Whether the notice can be dismissed by user. +- _options.type_ `[string]`: Type of notice, one of `default`, or `snackbar`. +- _options.speak_ `[boolean]`: Whether the notice content should be announced to screen readers. +- _options.actions_ `[Array]`: User actions to be presented with notice. # **createSuccessNotice** @@ -90,7 +91,7 @@ _Related_ _Parameters_ - _content_ `string`: Notice message. -- _options_ `?Object`: Optional notice options. +- _options_ `[Object]`: Optional notice options. _Returns_ @@ -108,7 +109,7 @@ _Related_ _Parameters_ - _content_ `string`: Notice message. -- _options_ `?Object`: Optional notice options. +- _options_ `[Object]`: Optional notice options. _Returns_ @@ -121,7 +122,7 @@ Returns an action object used in signalling that a notice is to be removed. _Parameters_ - _id_ `string`: Notice unique identifier. -- _context_ `?string`: Optional context (grouping) in which the notice is intended to appear. Defaults to default context. +- _context_ `[string]`: Optional context (grouping) in which the notice is intended to appear. Defaults to default context. _Returns_ diff --git a/packages/notices/src/store/actions.js b/packages/notices/src/store/actions.js index 5ea46e30a4d65d..f1771b6ca8ae2f 100644 --- a/packages/notices/src/store/actions.js +++ b/packages/notices/src/store/actions.js @@ -11,25 +11,24 @@ import { DEFAULT_CONTEXT, DEFAULT_STATUS } from './constants'; /** * Yields action objects used in signalling that a notice is to be created. * - * @param {?string} status Notice status. - * Defaults to `info`. - * @param {string} content Notice message. - * @param {?Object} options Notice options. - * @param {?string} options.context Context under which to - * group notice. - * @param {?string} options.id Identifier for notice. - * Automatically assigned - * if not specified. - * @param {?boolean} options.isDismissible Whether the notice can - * be dismissed by user. - * Defaults to `true`. - * @param {?boolean} options.speak Whether the notice - * content should be - * announced to screen - * readers. Defaults to - * `true`. - * @param {?Array} options.actions User actions to be - * presented with notice. + * @param {string} [status='info'] Notice status. + * @param {string} content Notice message. + * @param {Object} [options] Notice options. + * @param {string} [options.context='global'] Context under which to + * group notice. + * @param {string} [options.id] Identifier for notice. + * Automatically assigned + * if not specified. + * @param {boolean} [options.isDismissible=true] Whether the notice can + * be dismissed by user. + * @param {string} [options.type='default'] Type of notice, one of + * `default`, or `snackbar`. + * @param {boolean} [options.speak=true] Whether the notice + * content should be + * announced to screen + * readers. + * @param {Array} [options.actions] User actions to be + * presented with notice. */ export function* createNotice( status = DEFAULT_STATUS, content, options = {} ) { const { @@ -76,8 +75,8 @@ export function* createNotice( status = DEFAULT_STATUS, content, options = {} ) * * @see createNotice * - * @param {string} content Notice message. - * @param {?Object} options Optional notice options. + * @param {string} content Notice message. + * @param {Object} [options] Optional notice options. * * @return {Object} Action object. */ @@ -91,8 +90,8 @@ export function createSuccessNotice( content, options ) { * * @see createNotice * - * @param {string} content Notice message. - * @param {?Object} options Optional notice options. + * @param {string} content Notice message. + * @param {Object} [options] Optional notice options. * * @return {Object} Action object. */ @@ -106,8 +105,8 @@ export function createInfoNotice( content, options ) { * * @see createNotice * - * @param {string} content Notice message. - * @param {?Object} options Optional notice options. + * @param {string} content Notice message. + * @param {Object} [options] Optional notice options. * * @return {Object} Action object. */ @@ -121,8 +120,8 @@ export function createErrorNotice( content, options ) { * * @see createNotice * - * @param {string} content Notice message. - * @param {?Object} options Optional notice options. + * @param {string} content Notice message. + * @param {Object} [options] Optional notice options. * * @return {Object} Action object. */ @@ -133,9 +132,9 @@ export function createWarningNotice( content, options ) { /** * Returns an action object used in signalling that a notice is to be removed. * - * @param {string} id Notice unique identifier. - * @param {?string} context Optional context (grouping) in which the notice is - * intended to appear. Defaults to default context. + * @param {string} id Notice unique identifier. + * @param {string} [context='global'] Optional context (grouping) in which the notice is + * intended to appear. Defaults to default context. * * @return {Object} Action object. */ diff --git a/packages/notices/src/store/selectors.js b/packages/notices/src/store/selectors.js index b5daf3e024ccde..3a0bc75ad0f02a 100644 --- a/packages/notices/src/store/selectors.js +++ b/packages/notices/src/store/selectors.js @@ -29,6 +29,11 @@ const DEFAULT_NOTICES = []; * removal without notice. * @property {boolean} isDismissible Whether the notice can be dismissed by * user. Defaults to `true`. + * @property {string} type Type of notice, one of `default`, + * or `snackbar`. Defaults to `default`. + * @property {boolean} speak Whether the notice content should be + * announced to screen readers. Defaults to + * `true`. * @property {WPNoticeAction[]} actions User actions to present with notice. * */ @@ -39,7 +44,7 @@ const DEFAULT_NOTICES = []; * @property {string} label Message to use as action label. * @property {?string} url Optional URL of resource if action incurs * browser navigation. - * @property {?Function} callback Optional function to invoke when action is + * @property {?Function} onClick Optional function to invoke when action is * triggered by user. * */