feat: 🎸 option to disable multi-column sorting

Adds a new grid option `suppressMultiSort`, which when ensures that when
you sort one column, all others should be reset to no sort (as long as
they don't have suppressRemoveSort set to true).

Closes: #2913

Author: marcelo-portugal

misc/tutorial/102_sorting.ngdoc

@@ -11,6 +11,8 @@ UI-Grid allows you to sort rows. The feature is on by default. You can set the `
 Sorting can be disabled at the column level by setting `enableSorting: false` in the column def. See the last column below for an example.
 
 Multiple columns can be sorted by shift-clicking on the 2-n columns.  To see it in action, sort Gender then shift-click Name.
+This feature can be disabled by setting `suppressMultiSort: true`. When combined with the `suppressRemoveSort`, it allows you to at most sort one extra
+column beyond those with suppressRemoveSort turned on. This way, any column that is meant to stay sorted will not be modified.
 
 When sorting using the menus, the sorts are additive.  So if you have one column sorted and you pick another sort
 from a column menu, it will add on to the existing sort rather than replacing it.  You need to use the 'remove sort' option
@@ -59,6 +61,7 @@ For better performance with the following example, you can choose to load the ui
 
       vm.gridOptions1 = {
         enableSorting: true,
+        suppressMultiSort: true,
         columnDefs: [
           { field: 'name' },
           { field: 'gender' },
@@ -80,6 +83,7 @@ For better performance with the following example, you can choose to load the ui
 
        vm.gridOptions2 = {
         enableSorting: true,
+        suppressMultiSort: true,
         onRegisterApi: function( gridApi ) {
           vm.grid2Api = gridApi;
         },
@@ -122,7 +126,7 @@ For better performance with the following example, you can choose to load the ui
               }
             }
           },
-          { field: 'company', enableSorting: false  }
+          { field: 'company', enableSorting: true  }
         ]
       };
 

packages/core/src/js/factories/Grid.js

@@ -1957,7 +1957,7 @@ angular.module('ui.grid')
       direction = directionOrAdd;
     }
 
-    if (!add) {
+    if (!add || (self.options && self.options.suppressMultiSort)) {
       self.resetColumnSorting(column);
       column.sort.priority = undefined;
       // Get the actual priority since there may be columns which have suppressRemoveSort set

packages/core/src/js/factories/GridOptions.js

@@ -388,6 +388,16 @@ angular.module('ui.grid')
        */
       baseOptions.enableSorting = baseOptions.enableSorting !== false;
 
+      /**
+       * @ngdoc boolean
+       * @name suppressMultiSort
+       * @propertyOf ui.grid.class:GridOptions
+       * @description False by default. When enabled, this setting disables the ability
+       * to sort multiple columns by using the shift key or interacting with the column
+       * menu. Instead, each column sort will remove all other sorting.
+       */
+      baseOptions.suppressMultiSort = baseOptions.suppressMultiSort === true;
+
       /**
        * @ngdoc boolean
        * @name enableFiltering

packages/core/test/core/factories/Grid.spec.js

@@ -988,6 +988,10 @@ describe('Grid factory', function() {
 	});
 
 	describe('sortColumn', function() {
+		beforeEach(function() {
+			grid.options.suppressMultiSort = false;
+		});
+
 		it('should throw an exception if no column parameter is provided', function() {
 			expect(function() {
 				grid.sortColumn();
@@ -1060,6 +1064,17 @@ describe('Grid factory', function() {
 			expect(priorColumn.sort).toEqual({});
 		});
 
+		it('if another column has a sort, and both add and suppressMultiSort are set to true, that sort should be removed', function() {
+			var priorColumn = new GridColumn({name: 'b', sort: {direction: uiGridConstants.ASC}}, 0, grid);
+			grid.columns.push(priorColumn);
+			grid.options.suppressMultiSort = true;
+			grid.sortColumn(column, true);
+
+			expect(column.sort.direction).toEqual(uiGridConstants.ASC);
+			expect(column.sort.priority).toEqual(0);
+			expect(priorColumn.sort).toEqual({});
+		});
+
 		it('if another column has a sort, and add is set to true, then that sort should not be removed', function() {
 			var priorColumn = new GridColumn({name: 'b', sort: {direction: uiGridConstants.ASC, priority: 1}}, 0, grid);
 			grid.columns.push(priorColumn);
@@ -1083,6 +1098,18 @@ describe('Grid factory', function() {
 				expect(priorColumn.sort).toEqual({direction: uiGridConstants.ASC, priority: 1});
 			});
 
+		it('if another column has a sort, and both add and suppressMultiSort are set to true, but that other column has suppressRemoveSort, then it shouldn\'t be removed',
+			function() {
+				var priorColumn = new GridColumn({name: 'b', sort: {direction: uiGridConstants.ASC, priority: 1}, suppressRemoveSort: true}, 0, grid);
+				grid.columns.push(priorColumn);
+				grid.options.suppressMultiSort = true;
+				grid.sortColumn(column, true);
+
+				expect(column.sort.direction).toEqual(uiGridConstants.ASC);
+				expect(column.sort.priority).toEqual(2);
+				expect(priorColumn.sort).toEqual({direction: uiGridConstants.ASC, priority: 1});
+			});
+
 		it('if sortDirectionCycle is null-DESC-ASC, and sort is currently null, then should toggle to DESC, and reset priority', function() {
 			column.sort = {};
 			column.sortDirectionCycle = [null, uiGridConstants.DESC, uiGridConstants.ASC];

packages/core/test/core/factories/GridOptions.spec.js

@@ -40,6 +40,7 @@ describe('GridOptions factory', function () {
         scrollDebounce: 300,
         enableHiding: true,
         enableSorting: true,
+        suppressMultiSort: false,
         enableFiltering: false,
         filterContainer: 'headerCell',
         enableColumnMenus: true,
@@ -89,6 +90,7 @@ describe('GridOptions factory', function () {
         wheelScrollThrottle: 75,
         enableHiding: true,
         enableSorting: true,
+        suppressMultiSort: true,
         enableFiltering: true,
         filterContainer: 'columnMenu',
         enableColumnMenus: true,
@@ -136,6 +138,7 @@ describe('GridOptions factory', function () {
         scrollDebounce: 300,
         enableHiding: true,
         enableSorting: true,
+        suppressMultiSort: true,
         enableFiltering: true,
         filterContainer: 'columnMenu',
         enableColumnMenus: true,
@@ -188,6 +191,7 @@ describe('GridOptions factory', function () {
         filterContainer: 'columnMenu',
         enableHiding: false,
         enableSorting: false,
+        suppressMultiSort: false,
         enableColumnMenus: false,
         enableVerticalScrollbar: 0,
         enableHorizontalScrollbar: 0,
@@ -232,6 +236,7 @@ describe('GridOptions factory', function () {
         scrollDebounce: 300,
         enableHiding: false,
         enableSorting: false,
+        suppressMultiSort: false,
         enableFiltering: false,
         filterContainer: 'columnMenu',
         enableColumnMenus: false,