From 3c7bf038d8ab82eb91007a1e6664073b23e81b3a Mon Sep 17 00:00:00 2001
From: Weston Ruter <westonruter@git.wordpress.org>
Date: Sun, 29 Oct 2017 03:07:30 +0000
Subject: [PATCH] Customize: Fix interface alignment between `Setting` and
 `Control`, adding `defaults` to `wp.customize.Setting` and using
 `wp.customize.previewer` as default `previewer` param.

Also move jsdoc from class to `initialize` method and correct the param types.

Amends [41726], [42037], [32681].
See #42083, #30737.


git-svn-id: https://develop.svn.wordpress.org/trunk@42038 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/js/customize-controls.js | 44 +++++++++++++++++++++------
 1 file changed, 34 insertions(+), 10 deletions(-)

diff --git a/src/wp-admin/js/customize-controls.js b/src/wp-admin/js/customize-controls.js
index 3dfef9aa35..881bf2492d 100644
--- a/src/wp-admin/js/customize-controls.js
+++ b/src/wp-admin/js/customize-controls.js
@@ -348,24 +348,48 @@
 	 *
 	 * @see PHP class WP_Customize_Setting.
 	 *
+	 * @since 3.4.0
 	 * @class
 	 * @augments wp.customize.Value
 	 * @augments wp.customize.Class
-	 *
-	 * @param {object} id                The Setting ID.
-	 * @param {object} value             The initial value of the setting.
-	 * @param {object} options.previewer The Previewer instance to sync with.
-	 * @param {object} options.transport The transport to use for previewing. Supports 'refresh' and 'postMessage'.
-	 * @param {object} options.dirty
 	 */
 	api.Setting = api.Value.extend({
+
+		/**
+		 * Default params.
+		 *
+		 * @since 4.9.0
+		 * @var {object}
+		 */
+		defaults: {
+			transport: 'refresh',
+			dirty: false
+		},
+
+		/**
+		 * Initialize.
+		 *
+		 * @since 3.4.0
+		 *
+		 * @param {string}  id                          - The setting ID.
+		 * @param {*}       value                       - The initial value of the setting.
+		 * @param {object}  [options={}]                - Options.
+		 * @param {string}  [options.transport=refresh] - The transport to use for previewing. Supports 'refresh' and 'postMessage'.
+		 * @param {boolean} [options.dirty=false]       - Whether the setting should be considered initially dirty.
+		 * @param {object}  [options.previewer]         - The Previewer instance to sync with. Defaults to wp.customize.previewer.
+		 */
 		initialize: function( id, value, options ) {
-			var setting = this;
-			api.Value.prototype.initialize.call( setting, value, options );
+			var setting = this, params;
+			params = _.extend(
+				{ previewer: api.previewer },
+				setting.defaults,
+				options || {}
+			);
+
+			api.Value.prototype.initialize.call( setting, value, params );
 
 			setting.id = id;
-			setting.transport = setting.transport || 'refresh';
-			setting._dirty = options.dirty || false;
+			setting._dirty = params.dirty; // The _dirty property is what the Customizer reads from.
 			setting.notifications = new api.Notifications();
 
 			// Whenever the setting's value changes, refresh the preview.