feat(AnalyticalTable - useOrderedMultiSort): introduce new plugin hook

packages/main/src/components/AnalyticalTable/AnalyticalTable.cy.tsx

@@ -1988,6 +1988,115 @@ describe('AnalyticalTable', () => {
     cy.get('[data-visible-column-index="1"][data-visible-row-index="6"]').should('have.text', 25);
   });
 
+  it('plugin hook: useOrderedMultiSort', () => {
+    const TestComponent = ({ orderedIds }: { orderedIds: string[] }) => {
+      const columns = [
+        {
+          Header: 'Name',
+          accessor: 'name',
+          enableMultiSort: true
+        },
+        {
+          Header: 'Age',
+          accessor: 'age',
+          enableMultiSort: true
+        },
+        {
+          Header: 'Name 2',
+          accessor: 'name2',
+          enableMultiSort: true
+        },
+        {
+          Header: 'Age 2',
+          accessor: 'age2',
+          enableMultiSort: true
+        }
+      ];
+      const data = [
+        { name: 'Peter', age: 40, name2: 'Alissa', age2: 18 },
+        { name: 'Kristen', age: 40, name2: 'Randolph', age2: 21 },
+        { name: 'Peter', age: 30, name2: 'Rose', age2: 90 },
+        { name: 'Peter', age: 70, name2: 'Rose', age2: 22 },
+        { name: 'Kristen', age: 60, name2: 'Willis', age2: 80 },
+        { name: 'Kristen', age: 20, name2: 'Alissa', age2: 80 },
+        { name: 'Graham', age: 40, name2: 'Alissa', age2: 80 },
+        { name: 'Peter', age: 65, name2: 'Rose', age2: 26 },
+        { name: 'Graham', age: 65, name2: 'Rose', age2: 26 },
+        { name: 'Graham', age: 65, name2: 'Willis', age2: 26 },
+        { name: 'Graham', age: 62, name2: 'Willis', age2: 26 }
+      ];
+      return (
+        <AnalyticalTable
+          columns={columns}
+          data={data}
+          sortable
+          tableHooks={[AnalyticalTableHooks.useOrderedMultiSort(orderedIds)]}
+        />
+      );
+    };
+
+    cy.mount(<TestComponent orderedIds={['name', 'name2', 'age', 'age2']} />);
+    cy.findByText('Age').click();
+    cy.findByText('Sort Ascending').shadow().findByRole('listitem').click({ force: true });
+    cy.findByText('Name').click();
+    cy.findByText('Sort Ascending').shadow().findByRole('listitem').click({ force: true });
+
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="0"]').should('have.text', 'Graham');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="1"]').should('have.text', '40');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="0"]').should('have.text', 'Kristen');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="1"]').should('have.text', '20');
+
+    cy.findByText('Name 2').click();
+    cy.findByText('Sort Descending').shadow().findByRole('listitem').click({ force: true });
+
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="0"]').should('have.text', 'Graham');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="1"]').should('have.text', '62');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="2"]').should('have.text', 'Willis');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="0"]').should('have.text', 'Kristen');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="1"]').should('have.text', '60');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="2"]').should('have.text', 'Willis');
+
+    cy.findByText('Name 2').click();
+    cy.findByText('Clear Sorting').shadow().findByRole('listitem').click({ force: true });
+
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="0"]').should('have.text', 'Graham');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="1"]').should('have.text', '40');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="0"]').should('have.text', 'Kristen');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="1"]').should('have.text', '20');
+
+    cy.mount(<TestComponent orderedIds={['name2']} />);
+    cy.findByText('Age').click();
+    cy.findByText('Sort Ascending').shadow().findByRole('listitem').click({ force: true });
+    cy.findByText('Name').click();
+    cy.findByText('Sort Ascending').shadow().findByRole('listitem').click({ force: true });
+
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="0"]').should('have.text', 'Kristen');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="1"]').should('have.text', '20');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="0"]').should('have.text', 'Peter');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="1"]').should('have.text', '40');
+
+    cy.findByText('Age 2').click();
+    cy.findByText('Sort Ascending').shadow().findByRole('listitem').click({ force: true });
+
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="0"]').should('have.text', 'Kristen');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="1"]').should('have.text', '20');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="3"]').should('have.text', '80');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="0"]').should('have.text', 'Peter');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="1"]').should('have.text', '40');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="3"]').should('have.text', '18');
+
+    cy.findByText('Name 2').click();
+    cy.findByText('Sort Ascending').shadow().findByRole('listitem').click({ force: true });
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="0"]').should('have.text', 'Kristen');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="1"]').should('have.text', '20');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="2"]').should('have.text', 'Alissa');
+    cy.get('[data-visible-row-index="1"][data-visible-column-index="3"]').should('have.text', '80');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="0"]').should('have.text', 'Peter');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="1"]').should('have.text', '30');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="2"]').should('have.text', 'Rose');
+    cy.get('[data-visible-row-index="5"][data-visible-column-index="3"]').should('have.text', '90');
+  });
+
   cypressPassThroughTestsFactory(AnalyticalTable, { data, columns });
 });
 

packages/main/src/components/AnalyticalTable/AnalyticalTable.stories.tsx

@@ -335,6 +335,66 @@ export const PluginOnColumnResize: Story = {
   }
 };
 
+const orderedMultiSortColumns = [
+  {
+    Header: 'Name',
+    accessor: 'name',
+    enableMultiSort: true
+  },
+  {
+    Header: 'Age',
+    accessor: 'age',
+    enableMultiSort: true
+  },
+  {
+    Header: 'Name 2',
+    accessor: 'name2',
+    enableMultiSort: true
+  },
+  {
+    Header: 'Age 2',
+    accessor: 'age2',
+    enableMultiSort: true
+  }
+];
+const orderedMultiSortData = [
+  { name: 'Peter', age: 40, name2: 'Alissa', age2: 18 },
+  { name: 'Kristen', age: 40, name2: 'Randolph', age2: 21 },
+  { name: 'Peter', age: 30, name2: 'Rose', age2: 90 },
+  { name: 'Peter', age: 70, name2: 'Rose', age2: 22 },
+  { name: 'Kristen', age: 60, name2: 'Willis', age2: 80 },
+  { name: 'Kristen', age: 20, name2: 'Alissa', age2: 80 },
+  { name: 'Graham', age: 40, name2: 'Alissa', age2: 80 },
+  { name: 'Peter', age: 65, name2: 'Rose', age2: 26 },
+  { name: 'Graham', age: 65, name2: 'Rose', age2: 26 },
+  { name: 'Graham', age: 65, name2: 'Willis', age2: 26 },
+  { name: 'Graham', age: 62, name2: 'Willis', age2: 26 }
+];
+
+export const PluginOrderedMultiSort = {
+  name: 'Plugin: useOrderedMultiSort',
+  args: { orderedIds: ['name', 'name2', 'age', 'age2'] },
+  argTypes: {
+    orderedIds: {
+      control: 'array',
+      description:
+        'Defines the sort priority when sorting by multiple columns, starting with the first column ID.\n' +
+        '\n' +
+        '**Note:** Column IDs that are not found in the array use the default priority, so the first sorted column has a higher priority than the next sorted column.'
+    }
+  },
+  render(args) {
+    return (
+      <AnalyticalTable
+        columns={orderedMultiSortColumns}
+        data={orderedMultiSortData}
+        sortable
+        tableHooks={[AnalyticalTableHooks.useOrderedMultiSort(args.orderedIds)]}
+      />
+    );
+  }
+};
+
 export const TreeTable: Story = {
   args: {
     data: dataTree,
@@ -443,7 +503,7 @@ export const DynamicRowCount: Story = {
       description:
         'Select an option to change the height of the surrounding container of the table (in `px`). <br /> __Note__: This is not an actual prop of the table.'
     }
-  } as unknown,
+  },
   render: (args) => {
     return (
       <div style={{ height: `${args.containerHeight}px` }}>

packages/main/src/components/AnalyticalTable/PluginDisableRowSelection.mdx

@@ -1,5 +1,6 @@
 import { ImportStatement } from '@sb/components/Import';
 import { Canvas, Meta } from '@storybook/blocks';
+import { Footer } from '@sb/components';
 import * as ComponentStories from './AnalyticalTable.stories';
 
 <Meta title="Data Display / AnalyticalTable / Plugin: useRowDisableSelection" />
@@ -52,3 +53,5 @@ const data = [
   );
 };
 ```
+
+<Footer />

packages/main/src/components/AnalyticalTable/PluginIndeterminateRowSelection.mdx

@@ -1,5 +1,6 @@
 import { ImportStatement } from '@sb/components/Import';
 import { Canvas, Meta } from '@storybook/blocks';
+import { Footer } from '@sb/components';
 import { MessageStrip } from '../../webComponents/MessageStrip/index';
 import * as ComponentStories from './AnalyticalTable.stories';
 
@@ -48,3 +49,5 @@ The plugin hook allows passing a callback as parameter with the following struct
 
 The callback is fired, every time the internal `indeterminateRows` state is changed.
 The event parameter is an object, with all indeterminate rows by id (e.g. `{"0.1":true}`) and the table instance.
+
+<Footer />

packages/main/src/components/AnalyticalTable/PluginManualRowSelect.mdx

@@ -1,5 +1,6 @@
 import { ImportStatement } from '@sb/components/Import';
 import { Canvas, Meta } from '@storybook/blocks';
+import { Footer } from '@sb/components';
 import * as ComponentStories from './AnalyticalTable.stories';
 
 <Meta title="Data Display / AnalyticalTable / Plugin: useManualRowSelect" />
@@ -24,3 +25,5 @@ If this key is found on the original data row, and it is `true`, this row will b
   tableHooks={[AnalyticalTableHooks.useManualRowSelect('isSelected')]}
 />
 ```
+
+<Footer />

packages/main/src/components/AnalyticalTable/PluginOnColumnResize.mdx

@@ -1,5 +1,6 @@
 import { ImportStatement } from '@sb/components/Import';
 import { Canvas, Meta } from '@storybook/blocks';
+import { Footer } from '@sb/components';
 import * as ComponentStories from './AnalyticalTable.stories';
 
 <Meta title="Data Display / AnalyticalTable / Plugin: useOnColumnResize" />
@@ -39,3 +40,5 @@ const TableComponent = (props) => {
   );
 };
 ```
+
+<Footer />

packages/main/src/components/AnalyticalTable/PluginOrderedMultiSort.mdx

@@ -0,0 +1,79 @@
+import { ImportStatement } from '@sb/components/Import';
+import { Canvas, Meta } from '@storybook/blocks';
+import { ControlsWithNote, Footer } from '@sb/components';
+import * as ComponentStories from './AnalyticalTable.stories';
+
+<Meta title="Data Display / AnalyticalTable / Plugin: useOrderedMultiSort" />
+
+# AnalyticalTable Plugin: useOrderedMultiSort
+
+<ImportStatement moduleName={'AnalyticalTableHooks'} packageName={'@ui5/webcomponents-react'} />
+
+With the `useOrderedMultiSort` it's possible to define the sorting priority if multi-sort is enabled for the respective columns (`enableMultiSort: true`).
+
+It receives one parameter that defines the sorting priority by the column id.
+
+- `orderedIds: string[]`: Defines the sort priority when sorting by multiple columns, starting with the first column ID.
+
+**Note:** Column IDs that are not found in the array use the default priority, so the first sorted column has a higher priority than the next sorted column.
+
+## Example
+
+<Canvas sourceState="none" of={ComponentStories.PluginOrderedMultiSort} />
+
+### Current Parameter
+
+<ControlsWithNote of={ComponentStories.PluginOrderedMultiSort} hideHTMLPropsNote include={['orderedIds']} />
+
+### Code
+
+```jsx
+const columns = [
+  {
+    Header: 'Name',
+    accessor: 'name',
+    enableMultiSort: true
+  },
+  {
+    Header: 'Age',
+    accessor: 'age',
+    enableMultiSort: true
+  },
+  {
+    Header: 'Name 2',
+    accessor: 'name2',
+    enableMultiSort: true
+  },
+  {
+    Header: 'Age 2',
+    accessor: 'age2',
+    enableMultiSort: true
+  }
+];
+const data = [
+  { name: 'Peter', age: 40, name2: 'Alissa', age2: 18 },
+  { name: 'Kristen', age: 40, name2: 'Randolph', age2: 21 },
+  { name: 'Peter', age: 30, name2: 'Rose', age2: 90 },
+  { name: 'Peter', age: 70, name2: 'Rose', age2: 22 },
+  { name: 'Kristen', age: 60, name2: 'Willis', age2: 80 },
+  { name: 'Kristen', age: 20, name2: 'Alissa', age2: 80 },
+  { name: 'Graham', age: 40, name2: 'Alissa', age2: 80 },
+  { name: 'Peter', age: 65, name2: 'Rose', age2: 26 },
+  { name: 'Graham', age: 65, name2: 'Rose', age2: 26 },
+  { name: 'Graham', age: 65, name2: 'Willis', age2: 26 },
+  { name: 'Graham', age: 62, name2: 'Willis', age2: 26 }
+];
+const orderedIds = ['name', 'name2', 'age', 'age2'];
+const TableComponent = () => {
+  return (
+    <AnalyticalTable
+      columns={columns}
+      data={data}
+      sortable
+      tableHooks={[AnalyticalTableHooks.useOrderedMultiSort(orderedIds)]}
+    />
+  );
+};
+```
+
+<Footer />

packages/main/src/components/AnalyticalTable/Recipes.mdx

@@ -1,5 +1,6 @@
 import { TableOfContent } from '@sb/components';
 import { Meta } from '@storybook/blocks';
+import { Footer } from '@sb/components';
 import { MessageStrip } from '../../webComponents/index';
 
 <Meta title="Data Display / AnalyticalTable / Recipes" />
@@ -157,3 +158,5 @@ Please note that the internal react-table is resetting its hidden state after hi
     }}
   />
 ```
+
+<Footer />

packages/main/src/components/AnalyticalTable/pluginHooks/AnalyticalTableHooks.ts

@@ -1,6 +1,13 @@
 import { useIndeterminateRowSelection } from './useIndeterminateRowSelection.js';
 import { useManualRowSelect } from './useManualRowSelect.js';
 import { useOnColumnResize } from './useOnColumnResize.js';
+import { useOrderedMultiSort } from './useOrderedMultiSort.js';
 import { useRowDisableSelection } from './useRowDisableSelection.js';
 
-export { useIndeterminateRowSelection, useManualRowSelect, useOnColumnResize, useRowDisableSelection };
+export {
+  useIndeterminateRowSelection,
+  useManualRowSelect,
+  useOnColumnResize,
+  useOrderedMultiSort,
+  useRowDisableSelection
+};

packages/main/src/components/AnalyticalTable/pluginHooks/useOrderedMultiSort.ts

@@ -0,0 +1,35 @@
+/**
+ * A plugin hook for defining the sort priority when sorting by multiple columns, starting with the first column ID.
+ *
+ * **Note:** Column IDs that are not found in the array use the default priority, so the first sorted column has a higher priority than the next sorted column.
+ *
+ * @param {string[]} orderedIds - Array of column IDs, defining the sorting priority.
+ */
+export const useOrderedMultiSort = (orderedIds: string[]) => {
+  const useOrderedMultiSortPlugin = (hooks) => {
+    hooks.stateReducers.push((newState, action) => {
+      if (action.type === 'toggleSortBy') {
+        if (newState.sortBy.length <= 1) {
+          return newState;
+        } else {
+          const clonedSortBy = [...newState.sortBy];
+          const updatedSortBy = orderedIds.flatMap((sortedId) => {
+            const sortedItemIndex = clonedSortBy.findIndex((item) => item.id === sortedId);
+            if (sortedItemIndex !== -1) {
+              const sortedEntry = clonedSortBy[sortedItemIndex];
+              clonedSortBy.splice(sortedItemIndex, 1);
+              return [sortedEntry];
+            }
+            return [];
+          });
+          return { ...newState, sortBy: [...updatedSortBy, ...clonedSortBy] };
+        }
+      }
+      return newState;
+    });
+  };
+
+  useOrderedMultiSortPlugin.pluginName = 'useOrderedMultiSort';
+
+  return useOrderedMultiSortPlugin;
+};