Customize: Improve usability of Customize JS API.

* Eliminate need to pass both ID and instance in calls to `Values#add()` for panels, sections, controls, settings, partials, and notifications.
* Eliminate need to supply `content` param when constructing a `Control`.
* Unwrap the `options.params` object passed in constructors to just pass a flat `options`. (Back-compat is maintained.)
* Add support for `templateId` param for `Control` to override which template is used for the content.
* Remove unused `previewer` being supplied in `Control` instances.
* Rename `classes` to `containerClasses` on `Notification`.
* Automatically supply `instanceNumber` to improve stable sorting.
* Use `api.Notifications` for notifications in settings instead of `api.Value`.

See #30741.
Fixes #42083.


git-svn-id: https://develop.svn.wordpress.org/trunk@41726 602fd350-edb4-49c9-b593-d223f7449a82

3 files changed, 36 insertions, 21 deletions

diff --git a/src/wp-includes/js/customize-base.js b/src/wp-includes/js/customize-base.js
index 7db5084ada..3b943a61be 100644
--- a/src/wp-includes/js/customize-base.js
+++ b/src/wp-includes/js/customize-base.js
@@ -376,29 +376,44 @@ window.wp = window.wp || {};
 		/**
 		 * Add an item to the collection.
 		 *
-		 * @param {string} id    The ID of the item.
-		 * @param {mixed}  value The item instance.
-		 * @return {mixed} The new item's instance.
+		 * @param {string|wp.customize.Class} item - The item instance to add, or the ID for the instance to add. When an ID string is supplied, then itemObject must be provided.
+		 * @param {wp.customize.Class}        [itemObject] - The item instance when the first argument is a ID string.
+		 * @return {wp.customize.Class} The new item's instance, or an existing instance if already added.
 		 */
-		add: function( id, value ) {
-			if ( this.has( id ) )
-				return this.value( id );
+		add: function( item, itemObject ) {
+			var collection = this, id, instance;
+			if ( 'string' === typeof item ) {
+				id = item;
+				instance = itemObject;
+			} else {
+				if ( 'string' !== typeof item.id ) {
+					throw new Error( 'Unknown key' );
+				}
+				id = item.id;
+				instance = item;
+			}
 
-			this._value[ id ] = value;
-			value.parent = this;
+			if ( collection.has( id ) ) {
+				return collection.value( id );
+			}
+
+			collection._value[ id ] = instance;
+			instance.parent = collection;
 
 			// Propagate a 'change' event on an item up to the collection.
-			if ( value.extended( api.Value ) )
-				value.bind( this._change );
+			if ( instance.extended( api.Value ) ) {
+				instance.bind( collection._change );
+			}
 
-			this.trigger( 'add', value );
+			collection.trigger( 'add', instance );
 
 			// If a deferred object exists for this item,
 			// resolve it.
-			if ( this._deferreds[ id ] )
-				this._deferreds[ id ].resolve();
+			if ( collection._deferreds[ id ] ) {
+				collection._deferreds[ id ].resolve();
+			}
 
-			return this._value[ id ];
+			return collection._value[ id ];
 		},
 
 		/**
@@ -815,7 +830,7 @@ window.wp = window.wp || {};
 		 * @since 4.9.0
 		 * @var {string}
 		 */
-		classes: '',
+		containerClasses: '',
 
 		/**
 		 * Initialize notification.
@@ -829,7 +844,7 @@ window.wp = window.wp || {};
 		 * @param {string}   [params.setting] - Related setting ID.
 		 * @param {Function} [params.template] - Function for rendering template. If not provided, this will come from templateId.
 		 * @param {string}   [params.templateId] - ID for template to render the notification.
-		 * @param {string}   [params.classes] - Additional class names to add to the notification container.
+		 * @param {string}   [params.containerClasses] - Additional class names to add to the notification container.
 		 * @param {boolean}  [params.dismissible] - Whether the notification can be dismissed.
 		 */
 		initialize: function( code, params ) {
@@ -844,7 +859,7 @@ window.wp = window.wp || {};
 					setting: null,
 					template: null,
 					dismissible: false,
-					classes: ''
+					containerClasses: ''
 				},
 				params
 			);
diff --git a/src/wp-includes/js/customize-preview-widgets.js b/src/wp-includes/js/customize-preview-widgets.js
index b981788ed3..b2a60d892c 100644
--- a/src/wp-includes/js/customize-preview-widgets.js
+++ b/src/wp-includes/js/customize-preview-widgets.js
@@ -407,7 +407,7 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 				wasInserted = true;
 			} );
 
-			api.selectiveRefresh.partial.add( widgetPartial.id, widgetPartial );
+			api.selectiveRefresh.partial.add( widgetPartial );
 
 			if ( wasInserted ) {
 				sidebarPartial.reflowWidgets();
@@ -510,7 +510,7 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 						sidebarArgs: registeredSidebar
 					}
 				} );
-				api.selectiveRefresh.partial.add( partial.id, partial );
+				api.selectiveRefresh.partial.add( partial );
 			}
 		} );
 	};
diff --git a/src/wp-includes/js/customize-selective-refresh.js b/src/wp-includes/js/customize-selective-refresh.js
index 62bcfd8de0..3da7c0a237 100644
--- a/src/wp-includes/js/customize-selective-refresh.js
+++ b/src/wp-includes/js/customize-selective-refresh.js
@@ -877,7 +877,7 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 				partialOptions.constructingContainerContext = containerElement.data( 'customize-partial-placement-context' ) || {};
 				Constructor = self.partialConstructor[ containerElement.data( 'customize-partial-type' ) ] || self.Partial;
 				partial = new Constructor( id, partialOptions );
-				self.partial.add( partial.id, partial );
+				self.partial.add( partial );
 			}
 
 			/*
@@ -918,7 +918,7 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 			if ( ! partial ) {
 				Constructor = self.partialConstructor[ data.type ] || self.Partial;
 				partial = new Constructor( id, { params: data } );
-				self.partial.add( id, partial );
+				self.partial.add( partial );
 			} else {
 				_.extend( partial.params, data );
 			}