feat: add columnSort function as an option to ColumnPicker/GridMenu interfaces (#2066)

* feat: add columnSort function as an option to ColumnPicker/GridMenu interfaces

Author: mcallegario

docs/grid-functionalities/Column-Picker.md

@@ -19,4 +19,19 @@ this.gridOptions = {
 }
 ```
 #### UI Sample
-![image](https://user-images.githubusercontent.com/643976/71301681-6cfc3a00-2370-11ea-9c84-be880f345bcd.png)
+![image](https://user-images.githubusercontent.com/643976/71301681-6cfc3a00-2370-11ea-9c84-be880f345bcd.png)
+
+### How to change the "columnSort" option to sort columns
+The example demonstrates how to use the new alphabetical sorting feature:
+
+```typescript
+columnPicker: {
+  // enable the "columnSort" option to sort columns by name
+  columnSort: (item1: Column, item2: Column) => {
+    const nameA = item1.name?.toString().toLowerCase() || '';
+    const nameB = item2.name?.toString().toLowerCase() || '';
+    return nameA.localeCompare(nameB);
+  },
+  // ... other grid menu options
+}
+```

docs/grid-functionalities/Grid-Menu.md

@@ -127,3 +127,18 @@ this.gridOptions = {
    enableGridMenu: false,
 };
 ```
+
+### How to change the "columnSort" option to sort columns
+The example demonstrates how to use the new alphabetical sorting feature:
+
+```typescript
+gridMenu: {
+  // enable the "columnSort" option to sort columns by name
+  columnSort: (item1: Column, item2: Column) => {
+    const nameA = item1.name?.toString().toLowerCase() || '';
+    const nameB = item2.name?.toString().toLowerCase() || '';
+    return nameA.localeCompare(nameB);
+  },
+  // ... other grid menu options
+}
+```

packages/common/src/extensions/__tests__/slickColumnPicker.spec.ts

@@ -544,4 +544,104 @@ describe('ColumnPickerControl', () => {
       expect(control.getVisibleColumns()).toEqual(columnsMock);
     });
   });
+
+  describe('columnSort functionality', () => {
+    it('should sort columns alphabetically by name when "columnSort" function is provided', () => {
+      const handlerSpy = vi.spyOn(control.eventHandler, 'subscribe');
+      vi.spyOn(gridStub, 'getColumnIndex')
+        .mockReturnValue(undefined as any)
+        .mockReturnValue(1);
+
+      // Create columns with names that are not in alphabetical order
+      const unsortedColumnsMock: Column[] = [
+        { id: 'field1', field: 'field1', name: 'Zebra Field', width: 100 },
+        { id: 'field2', field: 'field2', name: 'Alpha Field', width: 75 },
+        { id: 'field3', field: 'field3', name: 'Beta Field', width: 75 },
+      ];
+
+      // Mock the shared service to return our custom columns
+      vi.spyOn(SharedService.prototype, 'allColumns', 'get').mockReturnValue(unsortedColumnsMock);
+      vi.spyOn(SharedService.prototype, 'visibleColumns', 'get').mockReturnValue(unsortedColumnsMock);
+      vi.spyOn(SharedService.prototype, 'columnDefinitions', 'get').mockReturnValue(unsortedColumnsMock);
+      vi.spyOn(gridStub, 'getColumns').mockReturnValue(unsortedColumnsMock);
+
+      // Define the columnSort function to sort alphabetically by name
+      gridOptionsMock.columnPicker!.columnSort = (col1: Column, col2: Column) => {
+        const nameA = String(col1.name || '').toLowerCase();
+        const nameB = String(col2.name || '').toLowerCase();
+        return nameA.localeCompare(nameB);
+      };
+
+      control.columns = unsortedColumnsMock;
+      control.init();
+
+      gridStub.onHeaderContextMenu.notify({ column: unsortedColumnsMock[1], grid: gridStub }, eventData as any, gridStub);
+
+      // Get the column labels from the menu in the order they appear
+      const liElmList = control.menuElement!.querySelectorAll<HTMLLIElement>('li');
+      const columnLabels: string[] = [];
+
+      // Extract text content from each column item (excluding force fit and sync resize buttons)
+      for (let i = 0; i < Math.min(liElmList.length, unsortedColumnsMock.length); i++) {
+        const labelSpan = liElmList[i].querySelector('.checkbox-label');
+        if (labelSpan && labelSpan.textContent) {
+          columnLabels.push(labelSpan.textContent.trim());
+        }
+      }
+
+      expect(handlerSpy).toHaveBeenCalledTimes(4);
+      expect(control.getAllColumns()).toEqual(unsortedColumnsMock);
+      expect(control.getVisibleColumns()).toEqual(unsortedColumnsMock);
+
+      // Verify that columns are displayed in alphabetical order: Alpha Field, Beta Field, Zebra Field
+      expect(columnLabels).toEqual(['Alpha Field', 'Beta Field', 'Zebra Field']);
+    });
+
+    it('should maintain the original column order when no "columnSort" function is provided', () => {
+      const handlerSpy = vi.spyOn(control.eventHandler, 'subscribe');
+      vi.spyOn(gridStub, 'getColumnIndex')
+        .mockReturnValue(undefined as any)
+        .mockReturnValue(1);
+
+      // Create columns in a specific order
+      const originalColumnsMock: Column[] = [
+        { id: 'field1', field: 'field1', name: 'Zebra Field', width: 100 },
+        { id: 'field2', field: 'field2', name: 'Alpha Field', width: 75 },
+        { id: 'field3', field: 'field3', name: 'Beta Field', width: 75 },
+      ];
+
+      // Mock the shared service to return our custom columns
+      vi.spyOn(SharedService.prototype, 'allColumns', 'get').mockReturnValue(originalColumnsMock);
+      vi.spyOn(SharedService.prototype, 'visibleColumns', 'get').mockReturnValue(originalColumnsMock);
+      vi.spyOn(SharedService.prototype, 'columnDefinitions', 'get').mockReturnValue(originalColumnsMock);
+      vi.spyOn(gridStub, 'getColumns').mockReturnValue(originalColumnsMock);
+
+      // Don't set columnSort, so it should remain undefined
+      gridOptionsMock.columnPicker!.columnSort = undefined;
+
+      control.columns = originalColumnsMock;
+      control.init();
+
+      gridStub.onHeaderContextMenu.notify({ column: originalColumnsMock[1], grid: gridStub }, eventData as any, gridStub);
+
+      // Get the column labels from the menu in the order they appear
+      const liElmList = control.menuElement!.querySelectorAll<HTMLLIElement>('li');
+      const columnLabels: string[] = [];
+
+      // Extract text content from each column item (excluding force fit and sync resize buttons)
+      for (let i = 0; i < Math.min(liElmList.length, originalColumnsMock.length); i++) {
+        const labelSpan = liElmList[i].querySelector('.checkbox-label');
+        if (labelSpan && labelSpan.textContent) {
+          columnLabels.push(labelSpan.textContent.trim());
+        }
+      }
+
+      expect(handlerSpy).toHaveBeenCalledTimes(4);
+      expect(control.getAllColumns()).toEqual(originalColumnsMock);
+      expect(control.getVisibleColumns()).toEqual(originalColumnsMock);
+
+      // Verify that columns maintain their original order: Zebra Field, Alpha Field, Beta Field
+      expect(columnLabels).toEqual(['Zebra Field', 'Alpha Field', 'Beta Field']);
+    });
+  });
 });

packages/common/src/extensions/extensionCommonUtils.ts

@@ -65,9 +65,13 @@ export function handleColumnPickerItemClick(this: SlickColumnPicker | SlickGridM
     context._areVisibleColumnDifferent = true;
     const columnId = event.target.dataset.columnid || '';
     const visibleColumns: Column[] = [];
-    context._columnCheckboxes.forEach((columnCheckbox: HTMLInputElement, idx: number) => {
-      if (columnCheckbox.checked) {
-        visibleColumns.push(context.columns[idx]);
+
+    // Iterate through columns and add those that have checked checkboxes to visibleColumns
+    context.columns.forEach((column: Column) => {
+      const columnId = column.id;
+      const checkbox = context._columnCheckboxes.find((cb: HTMLInputElement) => cb.dataset.columnid === columnId.toString());
+      if (checkbox?.checked) {
+        visibleColumns.push(column);
       }
     });
 
@@ -162,7 +166,13 @@ export function populateColumnPicker(this: SlickColumnPicker | SlickGridMenu, ad
   const isGridMenu = context instanceof SlickGridMenu;
   const menuPrefix = isGridMenu ? 'gridmenu-' : '';
 
-  for (const column of context.columns) {
+  let sortedColumns = context.columns;
+  if (typeof addonOptions?.columnSort === 'function') {
+    // create a sorted copy of the columns array based on the "name" property
+    sortedColumns = [...context.columns].sort(addonOptions.columnSort);
+  }
+
+  for (const column of sortedColumns) {
     const columnId = column.id;
     const columnLiElm = document.createElement('li');
     if ((column.excludeFromColumnPicker && !isGridMenu) || (column.excludeFromGridMenu && isGridMenu)) {

packages/common/src/interfaces/columnPicker.interface.ts

@@ -20,6 +20,9 @@ export interface ColumnPickerOption {
   /** Same as "columnTitle", except that it's a translation key which can be used on page load and/or when switching locale */
   columnTitleKey?: string;
 
+  /** Custom sort function for the columns in the column picker */
+  columnSort?: (item1: Column, item2: Column) => number;
+
   /** Defaults to "Force fit columns" which is 1 of the last 2 checkbox title shown at the end of the picker list */
   forceFitTitle?: string;
 

packages/common/src/interfaces/gridMenuOption.interface.ts

@@ -36,6 +36,9 @@ export interface GridMenuOption {
   /** Same as "columnTitle", except that it's a translation key which can be used on page load and/or when switching locale */
   columnTitleKey?: string;
 
+  /** Custom sort function for the columns in the grid menu */
+  columnSort?: (item1: Column, item2: Column) => number;
+
   /** Defaults to "left", which side to align the grid menu dropdown? */
   dropSide?: 'left' | 'right';