Add explanation of column set and another test to go with it.

dist/jquery.shuffle.js

@@ -937,18 +937,32 @@ Shuffle.prototype._getColumnSet = function( columnSpan, columns ) {
     return this.positions;
 
   // The item spans more than one column, figure out how many different
-  // places it could fit horizontally
+  // places it could fit horizontally.
+  // The group count is the number of places within the positions this block
+  // could fit, ignoring the current positions of items.
+  // Imagine a 2 column brick as the second item in a 4 column grid with
+  // 10px height each. Find the places it would fit:
+  // [10, 0, 0, 0]
+  //  |   |  |
+  //  *   *  *
+  //
+  // Then take the places which fit and get the bigger of the two:
+  // max([10, 0]), max([0, 0]), max([0, 0]) = [10, 0, 0]
+  //
+  // Next, find the first smallest number (the short column).
+  // [10, 0, 0]
+  //      |
+  //      *
+  //
+  // And that's where it should be placed!
   } else {
     var groupCount = columns + 1 - columnSpan;
     var groupY = [];
-    var groupColY;
 
-    // for each group potential horizontal position
+    // For how many possible positions for this item there are.
     for ( var i = 0; i < groupCount; i++ ) {
-      // make an array of colY values for that one group
-      groupColY = this.positions.slice( i, i + columnSpan );
-      // and get the max value of the array
-      groupY[i] = arrayMax( groupColY );
+      // Find the bigger value for each place it could fit.
+      groupY[i] = arrayMax( this.positions.slice( i, i + columnSpan ) );
     }
 
     return groupY;

dist/jquery.shuffle.modernizr.js

@@ -943,18 +943,32 @@ Shuffle.prototype._getColumnSet = function( columnSpan, columns ) {
     return this.positions;
 
   // The item spans more than one column, figure out how many different
-  // places it could fit horizontally
+  // places it could fit horizontally.
+  // The group count is the number of places within the positions this block
+  // could fit, ignoring the current positions of items.
+  // Imagine a 2 column brick as the second item in a 4 column grid with
+  // 10px height each. Find the places it would fit:
+  // [10, 0, 0, 0]
+  //  |   |  |
+  //  *   *  *
+  //
+  // Then take the places which fit and get the bigger of the two:
+  // max([10, 0]), max([0, 0]), max([0, 0]) = [10, 0, 0]
+  //
+  // Next, find the first smallest number (the short column).
+  // [10, 0, 0]
+  //      |
+  //      *
+  //
+  // And that's where it should be placed!
   } else {
     var groupCount = columns + 1 - columnSpan;
     var groupY = [];
-    var groupColY;
 
-    // for each group potential horizontal position
+    // For how many possible positions for this item there are.
     for ( var i = 0; i < groupCount; i++ ) {
-      // make an array of colY values for that one group
-      groupColY = this.positions.slice( i, i + columnSpan );
-      // and get the max value of the array
-      groupY[i] = arrayMax( groupColY );
+      // Find the bigger value for each place it could fit.
+      groupY[i] = arrayMax( this.positions.slice( i, i + columnSpan ) );
     }
 
     return groupY;

src/shuffle.js

@@ -920,18 +920,32 @@ Shuffle.prototype._getColumnSet = function( columnSpan, columns ) {
     return this.positions;
 
   // The item spans more than one column, figure out how many different
-  // places it could fit horizontally
+  // places it could fit horizontally.
+  // The group count is the number of places within the positions this block
+  // could fit, ignoring the current positions of items.
+  // Imagine a 2 column brick as the second item in a 4 column grid with
+  // 10px height each. Find the places it would fit:
+  // [10, 0, 0, 0]
+  //  |   |  |
+  //  *   *  *
+  //
+  // Then take the places which fit and get the bigger of the two:
+  // max([10, 0]), max([0, 0]), max([0, 0]) = [10, 0, 0]
+  //
+  // Next, find the first smallest number (the short column).
+  // [10, 0, 0]
+  //      |
+  //      *
+  //
+  // And that's where it should be placed!
   } else {
     var groupCount = columns + 1 - columnSpan;
     var groupY = [];
-    var groupColY;
 
-    // for each group potential horizontal position
+    // For how many possible positions for this item there are.
     for ( var i = 0; i < groupCount; i++ ) {
-      // make an array of colY values for that one group
-      groupColY = this.positions.slice( i, i + columnSpan );
-      // and get the max value of the array
-      groupY[i] = arrayMax( groupColY );
+      // Find the bigger value for each place it could fit.
+      groupY[i] = arrayMax( this.positions.slice( i, i + columnSpan ) );
     }
 
     return groupY;

test/specs.js

@@ -119,6 +119,48 @@ describe('Shuffle.js', function() {
       expect(shuffle.positions).toEqual([600, 450, 450]);
     });
 
+    it('can have a function for columns/gutters and span multiple columns', function() {
+      $shuffle.css({
+        width: '1200px'
+      });
+
+      var $kids = $shuffle.children();
+      $kids.css({
+        width: '300px',
+        height: '10px'
+      });
+
+      $kids.eq(1).css({
+        width: '600px'
+      });
+
+      $kids.eq(5).css({
+        width: '600px'
+      });
+
+      $kids.eq(6).css({
+        width: '900px'
+      });
+
+      $shuffle.shuffle({
+        columnWidth: function(containerWidth) {
+          expect(containerWidth).toBe(1200);
+          return 300;
+        },
+        gutterWidth: function() {
+          return 0;
+        }
+      });
+
+      var shuffle = $shuffle.data('shuffle');
+
+      expect(shuffle._getGutterSize(1200)).toBe(0);
+      expect(shuffle._getColumnSize(1200, 0)).toBe(300);
+      expect(shuffle.colWidth).toBe(300);
+      expect(shuffle.cols).toBe(4);
+      expect(shuffle.positions).toEqual([40, 40, 30, 30]);
+    });
+
     it('can filter by the data attribute', function(done) {
       var shuffle = $shuffle.shuffle({
         speed: 100
@@ -399,6 +441,27 @@ describe('Shuffle.js', function() {
         jasmine.clock().uninstall();
       });
 
+      it('can calculate column spans', function() {
+        expect(shuffle._getColumnSpan(50, 100, 3)).toBe(1);
+        expect(shuffle._getColumnSpan(200, 100, 3)).toBe(2);
+        expect(shuffle._getColumnSpan(200, 200, 3)).toBe(1);
+        expect(shuffle._getColumnSpan(300, 100, 3)).toBe(3);
+
+        // Column span should not be larger than the number of columns.
+        expect(shuffle._getColumnSpan(300, 50, 3)).toBe(3);
+
+        // Fix for percentage values.
+        expect(shuffle._getColumnSpan(100.02, 100, 4)).toBe(1);
+        expect(shuffle._getColumnSpan(99.98, 100, 4)).toBe(1);
+      });
+
+      it('can calculate column sets', function() {
+        // _getColumnSet(columnSpan, columns)
+        shuffle.positions = [150, 0, 0, 0];
+        expect(shuffle._getColumnSet(1, 4)).toEqual([150, 0, 0, 0]);
+        expect(shuffle._getColumnSet(2, 4)).toEqual([150, 0, 0]);
+      });
+
       it('can call appended with different options', function() {
 
         spyOn(shuffle, '_addItems').and.callFake(function() {});