Ticket #28709: 28709.wip.5.diff

src/wp-admin/customize.php

@@ -53 +53 @@
 wp_enqueue_script( 'customize-controls' );
 wp_enqueue_style( 'customize-controls' );
 
-wp_enqueue_script( 'accordion' );
-
 /**
  * Enqueue Customizer control scripts.
  *
@@ -160 +158 @@
                                 <?php endif; ?>
                         </div>
 
-                        <div id="customize-theme-controls"><ul>
-                                <?php
-                                foreach ( $wp_customize->containers() as $container ) {
-                                        $container->maybe_render();
-                                }
-                                ?>
-                        </ul></div>
+                        <div id="customize-theme-controls">
+                                <ul><?php // Panels and sections are managed here via JavaScript ?></ul>
+                        </div>
                 </div>
                 </div>
 
@@ -249 +243 @@
                 ),
                 'settings' => array(),
                 'controls' => array(),
+                'panels'   => array(),
+                'sections' => array(),
                 'nonce'    => array(
                         'save'    => wp_create_nonce( 'save-customize_' . $wp_customize->get_stylesheet() ),
                         'preview' => wp_create_nonce( 'preview-customize_' . $wp_customize->get_stylesheet() )
@@ -263 +259 @@
                 );
         }
 
-        // Prepare Customize Control objects to pass to Javascript.
+        // Prepare Customize Control objects to pass to JavaScript.
         foreach ( $wp_customize->controls() as $id => $control ) {
-                $control->to_json();
-                $settings['controls'][ $id ] = $control->json;
+                $settings['controls'][ $id ] = $control->json();
+        }
+
+        // Prepare Customize Section objects to pass to JavaScript.
+        foreach ( $wp_customize->sections() as $id => $section ) {
+                $settings['sections'][ $id ] = $section->json();
+        }
+
+        // Prepare Customize Panel objects to pass to JavaScript.
+        foreach ( $wp_customize->panels() as $id => $panel ) {
+                $settings['panels'][ $id ] = $panel->json();
+                foreach ( $panel->sections as $section_id => $section ) {
+                        $settings['sections'][ $section_id ] = $section->json();
+                }
         }
 
         ?>

src/wp-admin/js/accordion.js

@@ -58 +58 @@
                 });
         });
 
-        var sectionContent = $( '.accordion-section-content' );
-
         /**
          * Close the current accordion section and open a new one.
          *
@@ -69 +67 @@
         function accordionSwitch ( el ) {
                 var section = el.closest( '.accordion-section' ),
                         siblings = section.closest( '.accordion-container' ).find( '.open' ),
-                        content = section.find( sectionContent );
+                        content = section.find( '.accordion-section-content' );
 
                 // This section has no content and cannot be expanded.
                 if ( section.hasClass( 'cannot-expand' ) ) {
@@ -87 +85 @@
                         content.toggle( true ).slideToggle( 150 );
                 } else {
                         siblings.removeClass( 'open' );
-                        siblings.find( sectionContent ).show().slideUp( 150 );
+                        siblings.find( '.accordion-section-content' ).show().slideUp( 150 );
                         content.toggle( false ).slideToggle( 150 );
                         section.toggleClass( 'open' );
                 }
@@ -125 +123 @@
                 } else {
                         // Close all open sections in any accordion level.
                         siblings.removeClass( 'open' );
-                        siblings.find( sectionContent ).show().slideUp( 0 );
+                        siblings.find( '.accordion-section-content' ).show().slideUp( 0 );
                         content.show( 0, function() {
                                 position = content.offset().top;
                                 scroll = container.scrollTop();

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

@@ -1 +1 @@
 /* globals _wpCustomizeHeader, _wpMediaViewsL10n */
 (function( exports, $ ){
-        var api = wp.customize;
+        var bubbleChildValueChanges, Container, api = wp.customize;
 
         /**
          * @constructor
@@ -31 +31 @@
         });
 
         /**
+         * Watch all changes to Value properties, and bubble changes to parent Values instance
+         *
+         * @param {wp.customize.Class} instance
+         * @param {Array} properties  The names of the Value instances to watch.
+         */
+        bubbleChildValueChanges = function ( instance, properties ) {
+                $.each( properties, function ( i, key ) {
+                        instance[ key ].bind( function ( to, from ) {
+                                if ( instance.parent && to !== from ) {
+                                        instance.parent.trigger( 'change', instance );
+                                }
+                        } );
+                } );
+        };
+
+        /**
+         * Base class for Panel and Section
+         *
          * @constructor
          * @augments wp.customize.Class
          */
-        api.Control = api.Class.extend({
-                initialize: function( id, options ) {
-                        var control = this,
-                                nodes, radios, settings;
+        Container = api.Class.extend({
+                slideSpeed: 150,
 
-                        this.params = {};
-                        $.extend( this, options || {} );
+                initialize: function ( id, options ) {
+                        var self = this;
+                        self.id = id;
+                        self.params = {};
+                        $.extend( self, options || {} );
+                        self.container = $( self.params.content );
+
+                        self.priority = new api.Value();
+                        self.active = new api.Value();
+                        self.expanded = new api.Value();
+
+                        self.active.bind( function ( active ) {
+                                self.toggleActive( active && self.isContextuallyActive() );
+                                // @todo trigger 'activatged' and 'deactivated' events based on the expanded param?
+                        });
+                        self.expanded.bind( function ( expanded ) {
+                                self.toggleExpanded( expanded );
+                                // @todo trigger 'expanded' and 'collapsed' events based on the expanded param?
+                        });
 
-                        this.id = id;
-                        this.selector = '#customize-control-' + id.replace( /\]/g, '' ).replace( /\[/g, '-' );
-                        this.container = $( this.selector );
-                        this.active = new api.Value( this.params.active );
+                        self.attachEvents();
 
-                        settings = $.map( this.params.settings, function( value ) {
-                                return value;
+                        bubbleChildValueChanges( self, [ 'priority', 'active' ] );
+
+                        self.priority.set( isNaN( self.params.priority ) ? 100 : self.params.priority );
+                        self.active.set( true ); // @todo pass from params, eventually from active_callback when defining panel/section
+                        self.expanded.set( false ); // @todo True if deeplinking?
+                },
+
+                /**
+                 * Get the child models associated with this parent, sorting them by their priority Value.
+                 *
+                 * @param {String} parentType
+                 * @param {String} childType
+                 * @returns {Array}
+                 */
+                _children: function ( parentType, childType ) {
+                        var parent = this,
+                                children = [];
+                        api[ childType ].each( function ( child ) {
+                                if ( child[ parentType ].get() === parent.id ) {
+                                        children.push( child );
+                                }
+                        } );
+                        children.sort( function ( a, b ) {
+                                return a.priority() - b.priority();
+                        } );
+                        return children;
+                },
+
+                /**
+                 * To override by subclass, to return whether the container has active children.
+                 */
+                isContextuallyActive: function () {
+                        throw new Error( 'Must override with subclass.' );
+                },
+
+                /**
+                 * Handle changes to the active state.
+                 * This does not change the active state, it merely handles the behavior
+                 * for when it does change.
+                 *
+                 * To override by subclass, update the container's UI to reflect the provided active state.
+                 *
+                 * @param {Boolean} active
+                 */
+                toggleActive: function ( active ) {
+                        if ( active ) {
+                                this.container.stop( true, true ).slideDown();
+                        } else {
+                                this.container.stop( true, true ).slideUp();
+                        }
+                },
+
+                /**
+                 *
+                 */
+                activate: function () {
+                        this.active.set( true );
+                },
+
+                /**
+                 *
+                 */
+                deactivate: function () {
+                        this.active.set( false );
+                },
+
+                /**
+                 * To override by subclass, update the container's UI to reflect the provided active state.
+                 */
+                toggleExpanded: function () {
+                        throw new Error( 'Must override with subclass.' );
+                },
+
+                /**
+                 *
+                 */
+                expand: function () {
+                        this.expanded.set( true );
+                },
+
+                /**
+                 *
+                 */
+                collapse: function () {
+                        this.expanded( false );
+                },
+
+                /**
+                 *
+                 */
+                focus: function () {
+                        throw new Error( 'focus method must be overridden' );
+                }
+        });
+
+        /**
+         * @constructor
+         * @augments wp.customize.Class
+         */
+        api.Section = Container.extend({
+
+                /**
+                 * @param {String} id
+                 * @param {Array} options
+                 */
+                initialize: function ( id, options ) {
+                        var section = this;
+                        Container.prototype.initialize.call( section, id, options );
+
+                        section.panel = new api.Value();
+                        section.panel.bind( function ( id ) {
+                                $( section.container ).toggleClass( 'control-subsection', !! id );
                         });
+                        section.panel.set( section.params.panel || '' );
+                        bubbleChildValueChanges( section, [ 'panel' ] );
+                },
 
-                        api.apply( api, settings.concat( function() {
-                                var key;
+                /**
+                 *
+                 */
+                embed: function ( readyCallback ) {
+                        var panel_id,
+                                section = this;
+
+                        panel_id = this.panel.get();
+                        if ( ! panel_id ) {
+                                $( '#customize-theme-controls > ul' ).append( section.container );
+                                readyCallback();
+                        } else {
+                                api.panel( panel_id, function ( panel ) {
+                                        panel.embed();
+                                        panel.container.find( 'ul:first' ).append( section.container );
+                                        readyCallback();
+                                } );
+                        }
+                },
 
-                                control.settings = {};
-                                for ( key in control.params.settings ) {
-                                        control.settings[ key ] = api( control.params.settings[ key ] );
+                /**
+                 * Add behaviors for the accordion section
+                 */
+                attachEvents: function () {
+                        var section = this;
+
+                        // Expand/Collapse accordion sections on click.
+                        section.container.find( '.accordion-section-title' ).on( 'click keydown', function( e ) {
+                                if ( e.type === 'keydown' && 13 !== e.which ) { // "return" key
+                                        return;
                                 }
+                                e.preventDefault(); // Keep this AFTER the key filter above
 
-                                control.setting = control.settings['default'] || null;
-                                control.ready();
-                        }) );
+                                if ( section.expanded() ) {
+                                        section.collapse();
+                                } else {
+                                        section.expand();
+                                }
+                        });
+                },
+
+                /**
+                 * Return whether this section has any active controls.
+                 *
+                 * @returns {boolean}
+                 */
+                isContextuallyActive: function () {
+                        var section = this,
+                                controls = section.controls(),
+                                activeCount = 0;
+                        _( controls ).each( function ( control ) {
+                                if ( control.active() ) {
+                                        activeCount += 1;
+                                }
+                        } );
+                        return ( activeCount !== 0 );
+                },
+
+                /**
+                 * Get the controls that are associated with this section, sorted by their priority Value.
+                 *
+                 * @returns {Array}
+                 */
+                controls: function () {
+                        return this._children( 'section', 'control' );
+                },
+
+                /**
+                 * Update UI to reflect expanded state
+                 *
+                 * @param {Boolean} expanded
+                 */
+                toggleExpanded: function ( expanded ) {
+                        var section = this,
+                                content = section.container.find( '.accordion-section-content' );
+
+                        if ( expanded ) {
+
+                                if ( section.panel() ) {
+                                        api.panel( section.panel() ).expand();
+                                }
+
+                                api.section.each( function ( otherSection ) {
+                                        if ( otherSection !== section ) {
+                                                otherSection.collapse();
+                                        }
+                                });
+
+                                content.stop().slideDown( section.slideSpeed );
+                                section.container.addClass( 'open' );
+                        } else {
+
+                                section.container.removeClass( 'open' );
+                                content.slideUp( section.slideSpeed );
+                        }
+                },
+
+                /**
+                 * Bring the containing panel into view and then expand this section and bring it into view
+                 *
+                 * @todo This is an alias for expand(); do we need it?
+                 */
+                focus: function () {
+                        var section = this;
+                        // @todo What if it is not active? Return false?
+                        section.expand();
+                }
+        });
+
+        /**
+         * @constructor
+         * @augments wp.customize.Class
+         */
+        api.Panel = Container.extend({
+                initialize: function ( id, options ) {
+                        var panel = this;
+                        Container.prototype.initialize.call( panel, id, options );
+                },
+
+                /**
+                 *
+                 */
+                embed: function ( readyCallback ) {
+                        $( '#customize-theme-controls > ul' ).append( this.container );
+                        if ( readyCallback ) {
+                                readyCallback();
+                        }
+                },
+
+                /**
+                 *
+                 */
+                attachEvents: function () {
+                        var meta, panel = this;
+
+                        // Expand/Collapse accordion sections on click.
+                        panel.container.find( '.accordion-section-title' ).on( 'click keydown', function( e ) {
+                                if ( e.type === 'keydown' && 13 !== e.which ) { // "return" key
+                                        return;
+                                }
+                                e.preventDefault(); // Keep this AFTER the key filter above
+
+                                if ( ! panel.expanded() ) {
+                                        panel.expand();
+                                }
+                        });
+
+                        meta = panel.container.find( '.panel-meta:first' );
+
+                        meta.find( '> .accordion-section-title' ).on( 'click keydown', function( e ) {
+                                if ( e.type === 'keydown' && 13 !== e.which ) { // "return" key
+                                        return;
+                                }
+                                e.preventDefault(); // Keep this AFTER the key filter above
+
+                                if ( meta.hasClass( 'cannot-expand' ) ) {
+                                        return;
+                                }
+
+                                var content = meta.find( '.accordion-section-content:first' );
+                                if ( meta.hasClass( 'open' ) ) {
+                                        meta.toggleClass( 'open' );
+                                        content.slideUp( 150 );
+                                } else {
+                                        content.slideDown( 150 );
+                                        meta.toggleClass( 'open' );
+                                }
+                        });
+
+                },
+
+                /**
+                 * Get the sections that are associated with this panel, sorted by their priority Value.
+                 *
+                 * @returns {Array}
+                 */
+                sections: function () {
+                        return this._children( 'panel', 'section' );
+                },
+
+                /**
+                 * Return whether this section has any active sections.
+                 *
+                 * @returns {boolean}
+                 */
+                isContextuallyActive: function () {
+                        var panel = this,
+                                sections = panel.sections(),
+                                activeCount = 0;
+                        _( sections ).each( function ( section ) {
+                                if ( section.active() && section.isContextuallyActive() ) {
+                                        activeCount += 1;
+                                }
+                        } );
+                        return ( activeCount !== 0 );
+                },
+
+                /**
+                 * Update UI to reflect expanded state
+                 *
+                 * @param {Boolean} expanded
+                 */
+                toggleExpanded: function ( expanded ) {
+                        var position, scroll,
+                                panel = this,
+                                section = panel.container.closest( '.accordion-section' ),
+                                overlay = section.closest( '.wp-full-overlay' ),
+                                container = section.closest( '.accordion-container' ),
+                                siblings = container.find( '.open' ),
+                                topPanel = overlay.find( '#customize-theme-controls > ul > .accordion-section > .accordion-section-title' ).add( '#customize-info > .accordion-section-title' ),
+                                backBtn = overlay.find( '.control-panel-back' ),
+                                panelTitle = section.find( '.accordion-section-title' ).first(),
+                                content = section.find( '.control-panel-content' );
+
+                        if ( expanded ) {
+
+                                // Collapse any sibling sections/panels
+                                api.section.each( function ( section ) {
+                                        if ( ! section.panel() ) {
+                                                section.collapse(); // @todo If any sections are open, then the position calculation below will fire too early
+                                        }
+                                });
+                                api.panel.each( function ( otherPanel ) {
+                                        if ( panel !== otherPanel ) {
+                                                otherPanel.collapse(); // @todo the position calculation below probably will fire too early
+                                        }
+                                });
+
+                                content.show( 0, function() {
+                                        position = content.offset().top;
+                                        scroll = container.scrollTop();
+                                        content.css( 'margin-top', ( 45 - position - scroll ) );
+                                        section.addClass( 'current-panel' );
+                                        overlay.addClass( 'in-sub-panel' );
+                                        container.scrollTop( 0 );
+                                } );
+                                topPanel.attr( 'tabindex', '-1' );
+                                backBtn.attr( 'tabindex', '0' );
+                                backBtn.focus();
+                        } else {
+                                siblings.removeClass( 'open' );
+                                section.removeClass( 'current-panel' );
+                                overlay.removeClass( 'in-sub-panel' );
+                                content.delay( 180 ).hide( 0, function() {
+                                        content.css( 'margin-top', 'inherit' ); // Reset
+                                } );
+                                topPanel.attr( 'tabindex', '0' );
+                                backBtn.attr( 'tabindex', '-1' );
+                                panelTitle.focus();
+                                container.scrollTop( 0 );
+                        }
+                },
+
+                /**
+                 * Bring the containing panel into view and then expand this section and bring it into view
+                 */
+                focus: function () {
+                        var panel = this;
+                        // @todo What if it is not active? Return false?
+                        panel.expand();
+                }
+
+                // @todo Need to first exit out of the Panel
+        });
+
+        /**
+         * @constructor
+         * @augments wp.customize.Class
+         */
+        api.Control = api.Class.extend({
+                initialize: function( id, options ) {
+                        var control = this,
+                                nodes, radios, settings;
+
+                        control.params = {};
+                        $.extend( control, options || {} );
+
+                        control.id = id;
+                        control.selector = '#customize-control-' + id.replace( /\]/g, '' ).replace( /\[/g, '-' );
+                        control.container = control.params.content ? $( control.params.content ) : $( control.selector );
+
+                        control.section = new api.Value();
+                        control.priority = new api.Value();
+                        control.active = new api.Value();
 
                         control.elements = [];
 
-                        nodes  = this.container.find('[data-customize-setting-link]');
+                        nodes  = control.container.find('[data-customize-setting-link]');
                         radios = {};
 
                         nodes.each( function() {
-                                var node = $(this),
+                                var node = $( this ),
                                         name;
 
-                                if ( node.is(':radio') ) {
-                                        name = node.prop('name');
-                                        if ( radios[ name ] )
+                                if ( node.is( ':radio' ) ) {
+                                        name = node.prop( 'name' );
+                                        if ( radios[ name ] ) {
                                                 return;
+                                        }
 
                                         radios[ name ] = true;
                                         node = nodes.filter( '[name="' + name + '"]' );
                                 }
 
-                                api( node.data('customizeSettingLink'), function( setting ) {
+                                api( node.data( 'customizeSettingLink' ), function( setting ) {
                                         var element = new api.Element( node );
                                         control.elements.push( element );
                                         element.sync( setting );
@@ -90 +507 @@
                         });
 
                         control.active.bind( function ( active ) {
-                                control.toggle( active );
+                                control.toggleActive( active );
+                        } );
+
+                        control.section.set( control.params.section );
+                        control.priority.set( isNaN( control.params.priority ) ? 10 : control.params.priority );
+                        control.active.set( control.params.active );
+
+                        bubbleChildValueChanges( control, [ 'section', 'priority', 'active' ] );
+
+                        // Associate this control with its settings when they are created
+                        settings = $.map( control.params.settings, function( value ) {
+                                return value;
+                        });
+                        api.apply( api, settings.concat( function () {
+                                var key;
+
+                                control.settings = {};
+                                for ( key in control.params.settings ) {
+                                        control.settings[ key ] = api( control.params.settings[ key ] );
+                                }
+
+                                control.setting = control.settings['default'] || null;
+                                control.embed( function () {
+                                        control.ready();
+                                });
+                        }) );
+                },
+
+                /**
+                 * @param {Function} [readyCallback] Callback to fire when the embedding is done.
+                 */
+                embed: function ( readyCallback ) {
+                        var section_id,
+                                control = this;
+
+                        section_id = control.section.get();
+                        if ( ! section_id ) {
+                                throw new Error( 'A control must have an associated section.' );
+                        }
+
+                        // Defer until the associated section is available
+                        api.section( section_id, function ( section ) {
+                                section.embed( function () {
+                                        section.container.find( 'ul:first' ).append( control.container );
+                                        readyCallback();
+                                } );
                         } );
-                        control.toggle( control.active() );
                 },
 
                 /**
@@ -101 +562 @@
                 ready: function() {},
 
                 /**
-                 * Callback for change to the control's active state.
-                 *
-                 * Override function for custom behavior for the control being active/inactive.
+                 * Bring the containing section and panel into view and then this control into view, focusing on the first input
+                 */
+                focus: function () {
+                        throw new Error( 'Not implemented yet' );
+                },
+
+                /**
+                 * Update UI in response to a change in the control's active state.
+                 * This does not change the active state, it merely handles the behavior
+                 * for when it does change.
                  *
                  * @param {Boolean} active
                  */
-                toggle: function ( active ) {
+                toggleActive: function ( active ) {
                         if ( active ) {
                                 this.container.slideDown();
                         } else {
@@ -115 +583 @@
                         }
                 },
 
+                /**
+                 * @deprecated alias of toggleActive
+                 */
+                toggle: function ( active ) {
+                        return this.toggleActive( active );
+                },
+
+                /**
+                 * Shorthand way to enable the active state.
+                 */
+                activate: function () {
+                        this.active.set( true );
+                },
+
+                /**
+                 * Shorthand way to disable the active state.
+                 */
+                deactivate: function () {
+                        this.active.set( false );
+                },
+
                 dropdownInit: function() {
                         var control      = this,
                                 statuses     = this.container.find('.dropdown-status'),
@@ -575 +1064 @@
 
         // Create the collection of Control objects.
         api.control = new api.Values({ defaultConstructor: api.Control });
+        api.section = new api.Values({ defaultConstructor: api.Section });
+        api.panel = new api.Values({ defaultConstructor: api.Panel });
 
         /**
          * @constructor
@@ -979 +1470 @@
                 image:  api.ImageControl,
                 header: api.HeaderControl
         };
+        api.panelConstructor = {};
+        api.sectionConstructor = {};
 
         $( function() {
                 api.settings = window._wpCustomizeSettings;
@@ -1009 +1502 @@
                         }
                 });
 
+                // Expand/Collapse the main customizer customize info
+                $( '#customize-info' ).find( '> .accordion-section-title' ).on( 'click keydown', function( e ) {
+                        if ( e.type === 'keydown' && 13 !== e.which ) { // "return" key
+                                return;
+                        }
+                        e.preventDefault(); // Keep this AFTER the key filter above
+
+                        var section = $( this ).parent(),
+                                content = section.find( '.accordion-section-content:first' );
+
+                        if ( section.hasClass( 'cannot-expand' ) ) {
+                                return;
+                        }
+
+                        if ( section.hasClass( 'open' ) ) {
+                                section.toggleClass( 'open' );
+                                content.slideUp( 150 );
+                        } else {
+                                content.slideDown( 150 );
+                                section.toggleClass( 'open' );
+                        }
+                });
+
                 // Initialize Previewer
                 api.previewer = new api.Previewer({
                         container:   '#customize-preview',
@@ -1102 +1618 @@
                         $.extend( this.nonce, nonce );
                 });
 
+                // Create Settings
                 $.each( api.settings.settings, function( id, data ) {
                         api.create( id, id, data.value, {
                                 transport: data.transport,
@@ -1109 +1626 @@
                         } );
                 });
 
+                // Create Panels
+                $.each( api.settings.panels, function ( id, data ) {
+                        var constructor = api.panelConstructor[ data.type ] || api.Panel,
+                                panel;
+
+                        panel = new constructor( id, {
+                                params: data
+                        } );
+                        api.panel.add( id, panel );
+                });
+
+                // Create Sections
+                $.each( api.settings.sections, function ( id, data ) {
+                        var constructor = api.sectionConstructor[ data.type ] || api.Section,
+                                section;
+
+                        section = new constructor( id, {
+                                params: data
+                        } );
+                        api.section.add( id, section );
+                });
+
+                // Create Controls
+                // @todo factor this out
                 $.each( api.settings.controls, function( id, data ) {
                         var constructor = api.controlConstructor[ data.type ] || api.Control,
                                 control;
 
-                        control = api.control.add( id, new constructor( id, {
+                        control = new constructor( id, {
                                 params: data,
                                 previewer: api.previewer
-                        } ) );
+                        } );
+                        api.control.add( id, control );
                 });
 
+                /**
+                 * Sort panels, sections, controls by priorities. Hide empty sections and panels.
+                 */
+                api.reflowPaneContents = _.bind( function () {
+
+                        var appendContainer, activeElement, rootNodes = [];
+
+                        if ( document.activeElement ) {
+                                activeElement = $( document.activeElement );
+                        }
+
+                        api.panel.each( function ( panel ) {
+                                var sections = panel.sections();
+                                rootNodes.push( panel );
+                                appendContainer = panel.container.find( 'ul:first' );
+                                // @todo Skip doing any DOM manipulation if the ordering is already correct
+                                _( sections ).each( function ( section ) {
+                                        appendContainer.append( section.container );
+                                } );
+                        } );
+
+                        api.section.each( function ( section ) {
+                                var controls = section.controls();
+                                if ( ! section.panel() ) {
+                                        rootNodes.push( section );
+                                }
+                                appendContainer = section.container.find( 'ul:first' );
+                                // @todo Skip doing any DOM manipulation if the ordering is already correct
+                                _( controls ).each( function ( control ) {
+                                        appendContainer.append( control.container );
+                                } );
+                        } );
+
+                        // Sort the root elements
+                        rootNodes.sort( function ( a, b ) {
+                                return a.priority() - b.priority();
+                        } );
+                        appendContainer = $( '#customize-theme-controls > ul' );
+                        // @todo Skip doing any DOM manipulation if the ordering is already correct
+                        _( rootNodes ).each( function ( rootNode ) {
+                                appendContainer.append( rootNode.container );
+                        } );
+
+                        // Now re-trigger the active Value callbacks to that the panels and sections can decide whether they can be rendered
+                        api.panel.each( function ( panel ) {
+                                var value = panel.active();
+                                panel.active.callbacks.fireWith( panel.active, [ value, value ] );
+                        } );
+                        api.section.each( function ( section ) {
+                                var value = section.active();
+                                section.active.callbacks.fireWith( section.active, [ value, value ] );
+                        } );
+
+                        if ( activeElement ) {
+                                activeElement.focus();
+                        }
+                }, api );
+                api.reflowPaneContents = _.debounce( api.reflowPaneContents, 100 );
+                $( [ api.panel, api.section, api.control ] ).each( function ( i, values ) {
+                        values.bind( 'add', api.reflowPaneContents );
+                        values.bind( 'change', api.reflowPaneContents );
+                        values.bind( 'remove', api.reflowPaneContents );
+                } );
+                api.bind( 'ready', api.reflowPaneContents );
+
                 // Check if preview url is valid and load the preview frame.
                 if ( api.previewer.previewUrl() ) {
                         api.previewer.refresh();
@@ -1183 +1790 @@
                         event.preventDefault();
                 });
 
+                // Go back to the top-level Customizer accordion.
+                $( '#customize-header-actions' ).on( 'click keydown', '.control-panel-back', function( e ) {
+                        if ( e.type === 'keydown' && 13 !== e.which ) { // "return" key
+                                return;
+                        }
+
+                        e.preventDefault(); // Keep this AFTER the key filter above
+                        api.panel.each( function ( panel ) {
+                                panel.collapse();
+                        });
+                });
+
                 closeBtn.keydown( function( event ) {
                         if ( 9 === event.which ) // tab
                                 return;

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

@@ -404 +404 @@
          * @augments wp.customize.Control
          */
         api.Widgets.WidgetControl = api.Control.extend({
+
+                initialize: function ( id, options ) {
+                        var control = this;
+                        api.Control.prototype.initialize.call( control, id, options );
+                        control.expanded = new api.Value();
+                        control.expanded.bind( function ( expanded ) {
+                                control.toggleExpanded( expanded );
+                        });
+                        control.expanded.set( false );
+                },
+
                 /**
                  * Set up the control
                  */
@@ -529 +540 @@
                                 if ( sidebarWidgetsControl.isReordering ) {
                                         return;
                                 }
-                                self.toggleForm();
+                                self.expanded( ! self.expanded() );
                         } );
 
                         $closeBtn = this.container.find( '.widget-control-close' );
                         $closeBtn.on( 'click', function( e ) {
                                 e.preventDefault();
-                                self.collapseForm();
+                                self.collapse();
                                 self.container.find( '.widget-top .widget-action:first' ).focus(); // keyboard accessibility
                         } );
                 },
@@ -778 +789 @@
                  *
                  * @param {Boolean} active
                  */
-                toggle: function ( active ) {
+                toggleActive: function ( active ) {
                         this.container.toggleClass( 'widget-rendered', active );
                 },
 
@@ -1101 +1112 @@
                  * Expand the accordion section containing a control
                  */
                 expandControlSection: function() {
-                        var $section = this.container.closest( '.accordion-section' );
+                        api.section( this.section() ).expand();
+                },
 
-                        if ( ! $section.hasClass( 'open' ) ) {
-                                $section.find( '.accordion-section-title:first' ).trigger( 'click' );
-                        }
+                /**
+                 * Expand the widget form control
+                 */
+                expand: function () {
+                        this.expanded( true );
                 },
 
                 /**
                  * Expand the widget form control
+                 *
+                 * @deprecated alias of expand()
                  */
                 expandForm: function() {
-                        this.toggleForm( true );
+                        this.expand();
                 },
 
                 /**
                  * Collapse the widget form control
                  */
+                collapse: function () {
+                        this.expanded( false );
+                },
+
+                /**
+                 * Collapse the widget form control
+                 *
+                 * @deprecated alias of expand()
+                 */
                 collapseForm: function() {
-                        this.toggleForm( false );
+                        this.collapse();
                 },
 
                 /**
                  * Expand or collapse the widget control
                  *
+                 * @deprecated this is poor naming, and it is better to directly set control.expanded( showOrHide )
+                 *
                  * @param {boolean|undefined} [showOrHide] If not supplied, will be inverse of current visibility
                  */
                 toggleForm: function( showOrHide ) {
-                        var self = this, $widget, $inside, complete;
+                        if ( typeof showOrHide === 'undefined' ) {
+                                showOrHide = ! this.expanded();
+                        }
+                        this.expanded( showOrHide );
+                },
 
+                /**
+                 * Respond to change in the expanded state.
+                 *
+                 * @param {Boolean} expanded
+                 */
+                toggleExpanded: function ( expanded ) {
+
+                        var self = this, $widget, $inside, complete;
                         $widget = this.container.find( 'div.widget:first' );
                         $inside = $widget.find( '.widget-inside:first' );
-                        if ( typeof showOrHide === 'undefined' ) {
-                                showOrHide = ! $inside.is( ':visible' );
-                        }
 
-                        // Already expanded or collapsed, so noop
-                        if ( $inside.is( ':visible' ) === showOrHide ) {
-                                return;
-                        }
+                        if ( expanded ) {
+
+                                self.expandControlSection();
 
-                        if ( showOrHide ) {
                                 // Close all other widget controls before expanding this one
                                 api.control.each( function( otherControl ) {
                                         if ( self.params.type === otherControl.params.type && self !== otherControl ) {
-                                                otherControl.collapseForm();
+                                                otherControl.collapse();
                                         }
                                 } );
 
@@ -1164 +1198 @@
                                 self.container.trigger( 'expand' );
                                 self.container.addClass( 'expanding' );
                         } else {
+
                                 complete = function() {
                                         self.container.removeClass( 'collapsing' );
                                         self.container.removeClass( 'expanded' );
@@ -1189 +1224 @@
                  * the first input in the control
                  */
                 focus: function() {
-                        this.expandControlSection();
-                        this.expandForm();
+                        this.expand();
                         this.container.find( '.widget-content :focusable:first' ).focus();
                 },
 
@@ -1325 +1359 @@
                                 registeredSidebar = api.Widgets.registeredSidebars.get( this.params.sidebar_id );
 
                         this.setting.bind( function( newWidgetIds, oldWidgetIds ) {
-                                var widgetFormControls, $sidebarWidgetsAddControl, finalControlContainers, removedWidgetIds;
+                                var widgetFormControls, removedWidgetIds, priority;
 
                                 removedWidgetIds = _( oldWidgetIds ).difference( newWidgetIds );
 
@@ -1350 +1384 @@
                                 widgetFormControls.sort( function( a, b ) {
                                         var aIndex = _.indexOf( newWidgetIds, a.params.widget_id ),
                                                 bIndex = _.indexOf( newWidgetIds, b.params.widget_id );
+                                        return aIndex - bIndex;
+                                });
 
-                                        if ( aIndex === bIndex ) {
-                                                return 0;
-                                        }
-
-                                        return aIndex < bIndex ? -1 : 1;
-                                } );
-
-                                // Append the controls to put them in the right order
-                                finalControlContainers = _( widgetFormControls ).map( function( widgetFormControls ) {
-                                        return widgetFormControls.container[0];
-                                } );
-
-                                $sidebarWidgetsAddControl = self.$sectionContent.find( '.customize-control-sidebar_widgets' );
-                                $sidebarWidgetsAddControl.before( finalControlContainers );
+                                priority = 0;
+                                _( widgetFormControls ).each( function ( control ) {
+                                        control.priority( priority );
+                                        control.section( self.section() );
+                                        priority += 1;
+                                });
+                                self.priority( priority ); // Make sure sidebar control remains at end
 
                                 // Re-sort widget form controls (including widgets form other sidebars newly moved here)
                                 self._applyCardinalOrderClassNames();
@@ -1438 +1467 @@
                 },
 
                 /**
-                 * Show the sidebar section when it becomes visible.
+                 * Respond to change in active state to show the sidebar section.
                  *
-                 * Overrides api.Control.toggle()
+                 * Overrides api.Control.toggleActive()
                  *
                  * @param {Boolean} active
                  */
-                toggle: function ( active ) {
+                toggleActive: function ( active ) {
+                        // @todo this seems wrong. It seems we should be linking this.active with api.section( this.section.get() ).active
+
                         var $section, sectionSelector;
 
                         sectionSelector = '#accordion-section-sidebar-widgets-' + this.params.sidebar_id;
@@ -1584 +1615 @@
 
                         if ( showOrHide ) {
                                 _( this.getWidgetFormControls() ).each( function( formControl ) {
-                                        formControl.collapseForm();
+                                        formControl.collapse();
                                 } );
 
                                 this.$sectionContent.find( '.first-widget .move-widget' ).focus();
@@ -1651 +1682 @@
 
                         $widget = $( controlHtml );
 
+                        // @todo need to pass this in as the control's 'content' property
                         $control = $( '<li/>' )
                                 .addClass( 'customize-control' )
                                 .addClass( 'customize-control-' + controlType )
@@ -1674 +1706 @@
                         }
                         $control.attr( 'id', 'customize-control-' + settingId.replace( /\]/g, '' ).replace( /\[/g, '-' ) );
 
+                        // @todo Eliminate this
                         this.container.after( $control );
 
                         // Only create setting if it doesn't already exist (if we're adding a pre-existing inactive widget)
@@ -1733 +1766 @@
 
                         $control.slideDown( function() {
                                 if ( isExistingWidget ) {
-                                        widgetFormControl.expandForm();
+                                        widgetFormControl.expand();
                                         widgetFormControl.updateWidget( {
                                                 instance: widgetFormControl.setting(),
                                                 complete: function( error ) {

src/wp-includes/class-wp-customize-control.php

@@ -74 +74 @@
         public $input_attrs = array();
 
         /**
+         * @deprecated It is better to just call the json() method
          * @access public
          * @var array
          */
@@ -218 +219 @@
                 }
 
                 $this->json['type'] = $this->type;
+                $this->json['priority'] = $this->priority;
                 $this->json['active'] = $this->active();
+                $this->json['section'] = $this->section;
+                $this->json['content'] = $this->get_content();
+        }
+
+        /**
+         * Get the data to export to the client via JSON.
+         *
+         * @since 4.1.0
+         *
+         * @return array
+         */
+        public function json() {
+                $this->to_json();
+                return $this->json;
         }
 
         /**
@@ -242 +258 @@
         }
 
         /**
+         * Get the control's content for insertion into the Customizer pane.
+         *
+         * @since 4.1.0
+         *
+         * @return string
+         */
+        public final function get_content() {
+                ob_start();
+                $this->maybe_render();
+                $template = trim( ob_get_contents() );
+                ob_end_clean();
+                return $template;
+        }
+
+        /**
          * Check capabilities and render the control.
          *
          * @since 3.4.0

src/wp-includes/class-wp-customize-manager.php

@@ -878 +878 @@
 
                         if ( ! $section->panel ) {
                                 // Top-level section.
-                                $sections[] = $section;
+                                $sections[ $section->id ] = $section;
                         } else {
                                 // This section belongs to a panel.
                                 if ( isset( $this->panels [ $section->panel ] ) ) {
-                                        $this->panels[ $section->panel ]->sections[] = $section;
+                                        $this->panels[ $section->panel ]->sections[ $section->id ] = $section;
                                 }
                         }
                 }
@@ -899 +899 @@
                                 continue;
                         }
 
-                        usort( $panel->sections, array( $this, '_cmp_priority' ) );
-                        $panels[] = $panel;
+                        uasort( $panel->sections, array( $this, '_cmp_priority' ) );
+                        $panels[ $panel->id ] = $panel;
                 }
                 $this->panels = $panels;
 

src/wp-includes/class-wp-customize-panel.php

@@ -83 +83 @@
         public $sections;
 
         /**
+         * @since 4.1.0
+         * @access public
+         * @var string
+         */
+        public $type;
+
+        /**
          * Constructor.
          *
          * Any supplied $args override class property defaults.
@@ -110 +117 @@
         }
 
         /**
+         * Gather the parameters passed to client JavaScript via JSON.
+         *
+         * @since 4.1.0
+         *
+         * @return array The array to be exported to the client as JSON
+         */
+        public function json() {
+                $array = wp_array_slice_assoc( (array) $this, array( 'title', 'description', 'priority', 'type' ) );
+                $array['content'] = $this->get_content();
+                return $array;
+        }
+
+        /**
          * Checks required user capabilities and whether the theme has the
          * feature support required by the panel.
          *
@@ -130 +150 @@
         }
 
         /**
+         * Get the panel's content template for insertion into the Customizer pane.
+         *
+         * @since 4.1.0
+         *
+         * @return string
+         */
+        public final function get_content() {
+                ob_start();
+                $this->maybe_render();
+                $template = trim( ob_get_contents() );
+                ob_end_clean();
+                return $template;
+        }
+
+        /**
          * Check capabilities and render the panel.
          *
          * @since 4.0.0
@@ -189 +224 @@
          */
         protected function render_content() {
                 ?>
-                <li class="accordion-section control-section<?php if ( empty( $this->description ) ) echo ' cannot-expand'; ?>">
+                <li class="panel-meta accordion-section control-section<?php if ( empty( $this->description ) ) { echo ' cannot-expand'; } ?>">
                         <div class="accordion-section-title" tabindex="0">
                                 <span class="preview-notice"><?php
                                         /* translators: %s is the site/panel title in the Customizer */
@@ -203 +238 @@
                         <?php endif; ?>
                 </li>
                 <?php
-                foreach ( $this->sections as $section ) {
-                        $section->maybe_render();
-                }
         }
 }

src/wp-includes/class-wp-customize-section.php

@@ -92 +92 @@
         public $controls;
 
         /**
+         * @since 4.1.0
+         * @access public
+         * @var string
+         */
+        public $type;
+
+        /**
          * Constructor.
          *
          * Any supplied $args override class property defaults.
@@ -118 +125 @@
         }
 
         /**
+         * Gather the parameters passed to client JavaScript via JSON.
+         *
+         * @since 4.1.0
+         *
+         * @return array The array to be exported to the client as JSON
+         */
+        public function json() {
+                $array = wp_array_slice_assoc( (array) $this, array( 'title', 'description', 'priority', 'panel', 'type' ) );
+                $array['content'] = $this->get_content();
+                return $array;
+        }
+
+        /**
          * Checks required user capabilities and whether the theme has the
          * feature support required by the section.
          *
@@ -136 +156 @@
         }
 
         /**
+         * Get the section's content template for insertion into the Customizer pane.
+         *
+         * @since 4.1.0
+         *
+         * @return string
+         */
+        public final function get_content() {
+                ob_start();
+                $this->maybe_render();
+                $template = trim( ob_get_contents() );
+                ob_end_clean();
+                return $template;
+        }
+
+        /**
          * Check capabilities and render the section.
          *
          * @since 3.4.0
@@ -172 +207 @@
          */
         protected function render() {
                 $classes = 'control-section accordion-section';
-                if ( $this->panel ) {
-                        $classes .= ' control-subsection';
-                }
                 ?>
                 <li id="accordion-section-<?php echo esc_attr( $this->id ); ?>" class="<?php echo esc_attr( $classes ); ?>">
                         <h3 class="accordion-section-title" tabindex="0">
@@ -183 +215 @@
                         </h3>
                         <ul class="accordion-section-content">
                                 <?php if ( ! empty( $this->description ) ) : ?>
-                                <li><p class="description customize-section-description"><?php echo $this->description; ?></p></li>
+                                        <li class="customize-section-description-container">
+                                                <p class="description customize-section-description"><?php echo $this->description; ?></p>
+                                        </li>
                                 <?php endif; ?>
-                                <?php
-                                foreach ( $this->controls as $control )
-                                        $control->maybe_render();
-                                ?>
                         </ul>
                 </li>
                 <?php

src/wp-includes/js/customize-base.js

@@ -184 +184 @@
                         to = this.validate( to );
 
                         // Bail if the sanitized value is null or unchanged.
-                        if ( null === to || _.isEqual( from, to ) )
+                        if ( null === to || _.isEqual( from, to ) ) {
                                 return this;
+                        }
 
                         this._value = to;
                         this._dirty = true;