From 9368a2efa831384fc8964435002795c7326a33d2 Mon Sep 17 00:00:00 2001
From: Weston Ruter <westonruter@git.wordpress.org>
Date: Sun, 29 Oct 2017 00:14:06 +0000
Subject: [PATCH] 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         |  6 +++
 .../js/customize-selective-refresh.js         | 47 +++++++++++--------
 2 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/src/wp-admin/js/customize-controls.js b/src/wp-admin/js/customize-controls.js
index 764d787857..3dfef9aa35 100644
--- a/src/wp-admin/js/customize-controls.js
+++ b/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: '',
diff --git a/src/wp-includes/js/customize-selective-refresh.js b/src/wp-includes/js/customize-selective-refresh.js
index 9f78161511..b1169eb277 100644
--- a/src/wp-includes/js/customize-selective-refresh.js
+++ b/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 {Object} options
-		 * @param {Object} options.params
+		 * @param {string} id                      - Unique identifier for the partial instance.
+		 * @param {object} options                 - Options hash for the partial instance.
+		 * @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: [],
-					primarySetting: null,
-					containerInclusive: false,
-					fallbackRefresh: true // Note this needs to be false in a front-end editing context.
+					settings: []
 				},
-				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 );