CSS: Add jQuery.swap and warnings

Fixes #100
Closes #103

Author: dmethvin

Gruntfile.js

@@ -22,6 +22,7 @@ module.exports = function(grunt) {
 			"src/migrate.js",
 			"src/attributes.js",
 			"src/core.js",
+			"src/css.js",
 			"src/ajax.js",
 			"src/data.js",
 			"src/manipulation.js",

src/css.js

@@ -0,0 +1,44 @@
+
+var internalSwapCall = false;
+
+// If this version of jQuery has .swap(), don't false-alarm on internal uses
+if ( jQuery.swap ) {
+	jQuery.each( [ "height", "width", "reliableMarginRight" ], function( _, name ) {
+		var oldHook = jQuery.cssHooks[ name ] && jQuery.cssHooks[ name ].get;
+
+		if ( oldHook ) {
+			jQuery.cssHooks[ name ].get = function() {
+				var ret;
+
+				internalSwapCall = true;
+				ret = oldHook.apply( this, arguments );
+				internalSwapCall = false;
+				return ret;
+			};
+		}
+	});
+}
+
+jQuery.swap = function( elem, options, callback, args ) {
+	var ret, name,
+		old = {};
+
+	if ( !internalSwapCall ) {
+		migrateWarn( "jQuery.swap() is undocumented and deprecated" );
+	}
+
+	// Remember the old values, and insert the new ones
+	for ( name in options ) {
+		old[ name ] = elem.style[ name ];
+		elem.style[ name ] = options[ name ];
+	}
+
+	ret = callback.apply( elem, args || [] );
+
+	// Revert the old values
+	for ( name in options ) {
+		elem.style[ name ] = old[ name ];
+	}
+
+	return ret;
+};

test/css.js

@@ -0,0 +1,27 @@
+
+module("css");
+
+test( "jQuery.swap()", function( assert ) {
+	assert.expect( 6 );
+
+	var div = document.createElement( "div" );
+	div.style.borderWidth = "4px";
+
+	expectWarning( "External swap() call", function() {
+		jQuery.swap( div, { borderRightWidth: "5px" }, function( arg ) {
+
+			assert.equal( this.style.borderRightWidth, "5px", "style was changed" );
+			assert.equal( arg, 42, "arg was passed" );
+
+		}, [ 42 ] );
+	});
+	assert.equal( div.style.borderRightWidth, "4px", "style was restored" );
+
+	expectNoWarning( "Internal swap() call", function() {
+		var $fp = jQuery( "#firstp" ).width( "10em" ),
+			width = $fp.width();
+
+		assert.equal( $fp.hide().width(), width, "correct width" );
+	});
+
+});

test/index.html

@@ -34,6 +34,7 @@
 	<!-- Unit test files -->
 	<script src="migrate.js"></script>
 	<script src="core.js"></script>
+	<script src="css.js"></script>
 	<script src="data.js"></script>
 	<script src="attributes.js"></script>
 	<script src="manipulation.js"></script>

warnings.md

@@ -178,3 +178,8 @@ $(document).ajaxStart(function(){ $("#status").text("Ajax started"); });
 
 **Solution**: Replace any use of `.size()` with `.length`.
 
+### JQMIGRATE: jQuery.swap() is undocumented and deprecated
+
+**Cause**: The `jQuery.swap()` method temporarily exchanges a set of CSS properties. It was never documented as part of jQuery's public API and should not be used because it can cause performance problems due to forced layout.
+
+**Solution**: Rework the code to avoid calling `jQuery.swap()`, or explicitly set and restore the properties you need to change.