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.

Built from https://develop.svn.wordpress.org/trunk@42038


git-svn-id: http://core.svn.wordpress.org/trunk@41872 1a063a9b-81f0-0310-95a4-ce76da25c4cd

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.

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.9-beta4-42037';
+$wp_version = '4.9-beta4-42038';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.