Ticket #42114: 42114.1.diff

src/wp-admin/js/customize-controls.js

@@ -750 +750 @@
                 return equal;
         };
 
+        /**
+         * Highlight the existence of a button.
+         *
+         * This function reminds the user of a button represented by the specified
+         * UI element, after an optional delay. If the user focuses the element
+         * before the delay passes, the reminder is canceled.
+         *
+         * @since 4.9.0
+         *
+         * @param {jQuery} button The element to highlight.
+         * @param {object} [options]
+         * @param {number} [options.delay] Delay in milliseconds.
+         * @param {jQuery} [options.focusTarget] A target for user focus that
+         *      defaults to the highlighted element. If the user focuses the target
+         *      before the delay passes, the reminder is canceled. This option exists
+         *  to accommodate compound buttons containing auxiliary UI,
+         *  such as the Publish button augmented with a Settings button.
+         * @returns {Function} An idempotent function that cancels the reminder.
+         */
+        api.utils.highlightButton = function highlightButton( button, options ) {
+                var animationClass = 'button-see-me',
+                        canceled = false,
+                        delay,
+                        focusTarget;
+
+                options = options || {};
+                delay = 'delay' in options ? options.delay : 0;
+                focusTarget = 'focusTarget' in options ? options.focusTarget : button;
+
+                function cancelReminder() {
+                        canceled = true;
+                }
+
+                // Remove animation class in case it was already applied
+                button.removeClass( animationClass );
+
+                focusTarget.on( 'focusin', cancelReminder );
+                setTimeout( function() {
+                        focusTarget.off( 'focusin', cancelReminder );
+
+                        if ( ! canceled ) {
+                                button.addClass( animationClass );
+                        }
+                }, delay );
+
+                return cancelReminder;
+        };
+
         /**
          * Get current timestamp adjusted for server clock time.
          *

src/wp-admin/js/customize-nav-menus.js

@@ -1142 +1142 @@
                                 };
                         }
                         api.Section.prototype.onChangeExpanded.call( section, expanded, args );
+                },
+
+                /**
+                 * Highlight how a user may create new menu items.
+                 *
+                 * This method reminds the user to create new menu items and how.
+                 * It's exposed this way because this class knows best which UI needs
+                 * highlighted but those expanding this section know more about why and
+                 * when the affordance should be highlighted.
+                 *
+                 * @since 4.9.0
+                 */
+                highlightNewItemAffordance: function () {
+                        api.utils.highlightButton( this.contentContainer.find( '.add-new-menu-item' ), { delay: 2000 } );
                 }
         });
 
@@ -1383 +1397 @@
                         wp.a11y.speak( api.Menus.data.l10n.menuAdded );
 
                         // Focus on the new menu section.
-                        api.section( customizeId ).focus(); // @todo should we focus on the new menu's control and open the add-items panel? Thinking user flow...
+                        var editMenuSection = api.section( customizeId );
+                        editMenuSection.focus( {
+                                completeCallback: function() {
+                                        editMenuSection.highlightNewItemAffordance();
+                                }
+                        } ); // @todo should we focus on the new menu's control and open the add-items panel? Thinking user flow...api.section( customizeId ).focus(); // @todo should we focus on the new menu's control and open the add-items panel? Thinking user flow...
                 },
 
                 /**

src/wp-admin/js/customize-controls.js

@@ -763 +763 @@
          * @param {object} [options]
          * @param {number} [options.delay] Delay in milliseconds.
          * @param {jQuery} [options.focusTarget] A target for user focus that
-         *      defaults to the highlighted element. If the user focuses the target
+         *      defaults to the highlighted element. If the user focuses the target
          *      before the delay passes, the reminder is canceled. This option exists
-         *  to accommodate compound buttons containing auxiliary UI,
-         *  such as the Publish button augmented with a Settings button.
+         *      to accommodate compound buttons containing auxiliary UI,
+         *      such as the Publish button augmented with a Settings button.
          * @returns {Function} An idempotent function that cancels the reminder.
          */
         api.utils.highlightButton = function highlightButton( button, options ) {
@@ -783 +783 @@
                         canceled = true;
                 }
 
-                // Remove animation class in case it was already applied
+                // Remove animation class in case it was already applied.
                 button.removeClass( animationClass );
 
                 focusTarget.on( 'focusin', cancelReminder );