Customize: Allow panels and sections to have notifications just like controls can

[westonruter]

In #34893, the ability to show notifications on controls was added. In #35210 this is proposed to be extended at a global level to be able to show notifications at the root of the customizer. Between these two ends, there should also be the ability to show notifications at the panel and section level.

The Customize Posts plugin implements notifications for sections which could serve as a start for the patch here: ​https://github.com/xwp/wp-customize-posts/blob/0.8.2/js/customize-post-section.js#L825-L942

Once implemented, section notifications should be utilized for the Header Media section to show a notification when not previewing a URL that is eligible for a header video. See #38778. The section-level notification could be used in #40432 as well.

For more sample code, see:

• ​https://github.com/xwp/wp-customize-featured-content-demo/blob/8bf4d65/js/featured-items-panel.js#L45
• ​https://github.com/xwp/wp-customize-featured-content-demo/blob/8bf4d65/js/featured-items-panel.js#L69-L116
• ​https://github.com/xwp/wp-customize-featured-content-demo/blob/c748adf/php/class-featured-items-customize-panel.php#L47-L63

[celloexpressions]

While it's probably generally a better practice to use control-specific descriptions and notifications, header media is a good example of where it can make sense to do this for certain sections and panels. Another potential use case could be an info notification in the menus panel when there are no menus that invites users to create their first menu and assign it to their theme's locations.

[jbpaul17]

Punting to 4.8.1 per bug scrub earlier this week.

[westonruter]

​https://github.com/xwp/wordpress-develop/pull/260

[westonruter]

Handy reference to add a slew of notifications to all 4 contexts where they can appear (global, panel, section, control):

// Add global notifications.
_( [ 'none', 'error', 'warning', 'info', 'success' ] ).each( function( type ) {
        var code = 'example-' + type;
        wp.customize.notifications.add( code, new wp.customize.Notification( code, {
                dismissible: true,
                message: 'This is a sample ' + type + ' message.',
                type: type
        } ) );
} );

// Add notifications to the Widgets panel.
_( [ 'none', 'error', 'warning', 'info', 'success' ] ).each( function( type ) {
        var code = 'example-' + type;
        wp.customize.panel( 'widgets' ).notifications.add( code, new wp.customize.Notification( code, {
                dismissible: true,
                message: 'This is a sample ' + type + ' message.',
                type: type
        } ) );
} );

// Add notifications to the Site Identity section.
_( [ 'none', 'error', 'warning', 'info', 'success' ] ).each( function( type ) {
        var code = 'example-' + type;
        wp.customize.section( 'title_tagline' ).notifications.add( code, new wp.customize.Notification( code, {
                dismissible: true,
                message: 'This is a sample ' + type + ' message.',
                type: type
        } ) );
} );

// Add notifications to the site title control.
_( [ 'none', 'error', 'warning', 'info', 'success' ] ).each( function( type ) {
        var code = 'example-' + type;
        wp.customize.control( 'blogname' ).notifications.add( code, new wp.customize.Notification( code, {
                dismissible: true,
                message: 'This is a sample ' + type + ' message.',
                type: type
        } ) );
} );

[westonruter]

In 41390:

Customize: Add notifications API to sections and panels.

• Adds a notifications property to instances of wp.customize.Panel and wp.customize.Section.
• Adds a setupNotifications() method to Panel, Section, and Control.
• Adds a getNotificationsContainerElement() method to the Panel and Section classes, like Control has.
• Replace hard-coded notification in header media section with a notification.
• Limit rendering notifications to panels and sections that are expanded, and to controls that have an expanded section.

See #34893, #35210, #38778.
Fixes #38794.

[westonruter]

In 42031:

Customize: Improve Media control accessibility and compatibility for settings passed as arrays or as solitary setting.

• Eliminate Media control template from having dependency on params.settings.default for element ID, to fix compat with params.settings array or single params.setting. See #36167.
• Move description out of label and add aria-describedby to Media control's Select button. See #30738, #33085.
• Obtain notification container whenever content is (re-)rendered (such as for Media control). See #38794.
• Re-render notifications after control content is re-rendered, if control is in expanded section. See #38794.

Amends [41390].
See #36167, #38794, #33085, #30738.

[westonruter]

Dev note: ​https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/