Customize: Support instantiation of partials with flat/unwrapped params for parity with controls, sections, and panels in [41726].

* Passing `options.params` when constructing `Partial` is now deprecated in favor of just passing `options`.
* Improve usage of jsdoc in JS `Partial` class.
* Also add `defaults` property to `wp.customize.selectiveRefresh.Partial` class for parity with `Control`.

See #42083.


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

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

@@ -3401,6 +3401,12 @@
 	api.Control = api.Class.extend({
 		defaultActiveArguments: { duration: 'fast', completeCallback: $.noop },
 
+		/**
+		 * Default params.
+		 *
+		 * @since 4.9.0
+		 * @var {object}
+		 */
 		defaults: {
 			label: '',
 			description: '',

src/wp-includes/js/customize-selective-refresh.js

@@ -32,28 +32,37 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 	 * @class
 	 * @augments wp.customize.Class
 	 * @since 4.5.0
-	 *
-	 * @param {string} id                              Unique identifier for the control instance.
-	 * @param {object} options                         Options hash for the control instance.
-	 * @param {object} options.params
-	 * @param {string} options.params.type             Type of partial (e.g. nav_menu, widget, etc)
-	 * @param {string} options.params.selector         jQuery selector to find the container element in the page.
-	 * @param {array}  options.params.settings         The IDs for the settings the partial relates to.
-	 * @param {string} options.params.primarySetting   The ID for the primary setting the partial renders.
-	 * @param {bool}   options.params.fallbackRefresh  Whether to refresh the entire preview in case of a partial refresh failure.
 	 */
 	Partial = self.Partial = api.Class.extend(/** @lends wp.customize.SelectiveRefresh.Partial.prototype */{
 
 		id: null,
 
+		/**
+		 * Default params.
+		 *
+		 * @since 4.9.0
+		 * @var {object}
+		 */
+		defaults: {
+			selector: null,
+			primarySetting: null,
+			containerInclusive: false,
+			fallbackRefresh: true // Note this needs to be false in a front-end editing context.
+		},
+
 		/**
 		 * Constructor.
 		 *
 		 * @since 4.5.0
 		 *
-		 * @param {string} id - Partial ID.
+		 * @param {string} id                      - Unique identifier for the partial instance.
-		 * @param {Object} options
+		 * @param {object} options                 - Options hash for the partial instance.
-		 * @param {Object} options.params
+		 * @param {string} options.type            - Type of partial (e.g. nav_menu, widget, etc)
+		 * @param {string} options.selector        - jQuery selector to find the container element in the page.
+		 * @param {array}  options.settings        - The IDs for the settings the partial relates to.
+		 * @param {string} options.primarySetting  - The ID for the primary setting the partial renders.
+		 * @param {bool}   options.fallbackRefresh - Whether to refresh the entire preview in case of a partial refresh failure.
+		 * @param {object} [options.params]        - Deprecated wrapper for the above properties.
 		 */
 		initialize: function( id, options ) {
 			var partial = this;
@@ -62,13 +71,10 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 
 			partial.params = _.extend(
 				{
-					selector: null,
+					settings: []
-					settings: [],
-					primarySetting: null,
-					containerInclusive: false,
-					fallbackRefresh: true // Note this needs to be false in a front-end editing context.
 				},
-				options.params || {}
+				partial.defaults,
+				options.params || options
 			);
 
 			partial.deferred = {};
@@ -917,7 +923,10 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 			var Constructor, partial = self.partial( id );
 			if ( ! partial ) {
 				Constructor = self.partialConstructor[ data.type ] || self.Partial;
-				partial = new Constructor( id, { params: data } );
+				partial = new Constructor(
+					id,
+					_.extend( { params: data }, data ) // Inclusion of params alias is for back-compat for custom partials that expect to augment this property.
+				);
 				self.partial.add( partial );
 			} else {
 				_.extend( partial.params, data );