refactor: rewrite sorting state in typescript and add tests (#19589)

* refactor: rewrite sorting state in typescript and add tests

* fix: update table sort types given DataTable rewrite

Author: adamalston

packages/react/src/components/DataTable/DataTable.tsx

@@ -17,7 +17,7 @@ import React, {
 } from 'react';
 import isEqual from 'react-fast-compare';
 import getDerivedStateFromProps from './state/getDerivedStateFromProps';
-import { getNextSortState } from './state/sorting';
+import { getNextSortState, type SortRowFn } from './state/sorting';
 import type { DataTableSortState } from './state/sortStates';
 import { getCellId } from './tools/cells';
 import denormalize from './tools/denormalize';
@@ -260,21 +260,7 @@ export interface DataTableProps<RowType, ColTypes extends any[]>
   ) => ReactElement;
   rows: Omit<DataTableRow<ColTypes>, 'cells'>[];
   size?: DataTableSize;
-  sortRow?: (
-    cellA: any,
-    cellB: any,
-    options: {
-      sortDirection: DataTableSortState;
-      sortStates: Record<DataTableSortState, DataTableSortState>;
-      locale: string;
-      key: string;
-      compare: (
-        a: number | string,
-        b: number | string,
-        locale?: string
-      ) => number;
-    }
-  ) => number;
+  sortRow?: SortRowFn;
   stickyHeader?: boolean;
   useStaticWidth?: boolean;
   useZebraStyles?: boolean;

packages/react/src/components/DataTable/TableHeader.tsx

@@ -19,11 +19,10 @@ import {
   ArrowsVertical as Arrows,
 } from '@carbon/icons-react';
 import classNames from 'classnames';
-import { sortStates } from './state/sorting';
 import { useId } from '../../internal/useId';
 import { usePrefix } from '../../internal/usePrefix';
 import { TranslateWithId } from '../../types/common';
-import { DataTableSortState } from './state/sortStates';
+import { sortStates, type DataTableSortState } from './state/sortStates';
 import { AILabel } from '../AILabel';
 import { isComponentElement } from '../../internal';
 

packages/react/src/components/DataTable/state/__tests__/sorting-test.js

@@ -1,13 +1,14 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2025
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
+import { sortStates } from '../sortStates';
+
 describe('sorting state', () => {
   let sorting;
-  let sortStates;
   let initialSortState;
   let getNextSortDirection;
   let getNextSortState;
@@ -18,7 +19,6 @@ describe('sorting state', () => {
     }));
 
     sorting = require('../sorting');
-    sortStates = sorting.sortStates;
     initialSortState = sorting.initialSortState;
     getNextSortDirection = sorting.getNextSortDirection;
     getNextSortState = sorting.getNextSortState;
@@ -190,5 +190,29 @@ describe('sorting state', () => {
         rowIds: ['a', 'b', 'c'],
       });
     });
+
+    it('should sort without `sortRow` being provided', () => {
+      const state = getNextSortState({ locale: 'en' }, mockState, { key: 'a' });
+
+      expect(state.rowIds).toEqual(['b', 'a', 'c']);
+    });
+
+    it('should reset sort direction when a different header is sorted', () => {
+      const state1 = getNextSortState(mockProps, mockState, { key: 'a' });
+      const state2 = getNextSortState(
+        mockProps,
+        { ...mockState, ...state1 },
+        { key: 'b' }
+      );
+
+      expect(state2.sortDirection).toBe(sortStates.ASC);
+    });
+
+    it('should handle empty `cellsById`', () => {
+      const emptyState = { ...mockState, cellsById: {} };
+      const state = getNextSortState(mockProps, emptyState, { key: 'a' });
+
+      expect(state.rowIds).toEqual(['b', 'a', 'c']);
+    });
   });
 });

packages/react/src/components/DataTable/state/sorting.js

@@ -0,0 +1,123 @@
+/**
+ * Copyright IBM Corp. 2016, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { sortStates, type DataTableSortState } from './sortStates';
+import { sortRows } from '../tools/sorting';
+import type { DataTableCell } from '../DataTable';
+
+export interface SortRowParams {
+  key: string;
+  sortDirection: DataTableSortState;
+  sortStates: Record<DataTableSortState, DataTableSortState>;
+  locale: string;
+  compare: (a: string | number, b: string | number, locale?: string) => number;
+}
+
+export type SortRowFn = (
+  cellA: any,
+  cellB: any,
+  options: SortRowParams
+) => number;
+
+interface Props {
+  locale?: string;
+  sortRow?: SortRowFn;
+}
+
+interface State<ColTypes extends any[]> {
+  rowIds: string[];
+  cellsById: Record<string, DataTableCell<ColTypes[number]>>;
+  initialRowOrder: string[];
+  sortHeaderKey: string | null;
+  sortDirection: DataTableSortState;
+}
+
+export const initialSortState = sortStates.NONE;
+
+/**
+ * Gets the next sort direction for a header.
+ *
+ * @param prevHeader - Key of the previously sorted header.
+ * @param currentHeader - Key of the currently selected header.
+ * @param prevState - Previous sort direction.
+ */
+export const getNextSortDirection = (
+  prevHeader: string,
+  currentHeader: string,
+  prevState: DataTableSortState
+): DataTableSortState => {
+  // Cycle for sorting the same header: NONE -> ASC -> DESC -> NONE.
+  if (prevHeader === currentHeader) {
+    switch (prevState) {
+      case sortStates.NONE:
+        return sortStates.ASC;
+      case sortStates.ASC:
+        return sortStates.DESC;
+      case sortStates.DESC:
+        return sortStates.NONE;
+    }
+  }
+
+  // Sorting a new header starts at ascending order.
+  return sortStates.ASC;
+};
+
+/**
+ * Gets the next sort state.
+ *
+ * @param props - Component props.
+ * @param state - Current table state.
+ * @param key - Header key to sort by.
+ */
+export const getNextSortState = <ColTypes extends any[]>(
+  props: Props,
+  state: State<ColTypes>,
+  { key }: { key: string }
+): Pick<State<ColTypes>, 'sortHeaderKey' | 'sortDirection' | 'rowIds'> => {
+  const { sortDirection, sortHeaderKey } = state;
+
+  const nextSortDirection = getNextSortDirection(
+    key,
+    sortHeaderKey ?? '',
+    sortDirection
+  );
+
+  return getSortedState(props, state, key, nextSortDirection);
+};
+
+/**
+ * Gets a sort state update.
+ *
+ * @param props - Component props.
+ * @param state - Current state of the table.
+ * @param key - Header key to sort by.
+ * @param sortDirection - Sort direction to apply.
+ */
+export const getSortedState = <ColTypes extends any[]>(
+  { locale, sortRow }: Props,
+  { rowIds, cellsById, initialRowOrder }: State<ColTypes>,
+  key: string,
+  sortDirection: DataTableSortState
+): Pick<State<ColTypes>, 'rowIds' | 'sortDirection' | 'sortHeaderKey'> => {
+  const nextRowIds =
+    sortDirection !== sortStates.NONE
+      ? sortRows({
+          rowIds,
+          cellsById,
+          sortDirection,
+          key,
+          locale,
+          sortRow,
+        })
+      : initialRowOrder;
+
+  return {
+    sortHeaderKey: key,
+    sortDirection,
+    rowIds: nextRowIds,
+  };
+};

packages/react/src/components/DataTable/state/sorting.ts

@@ -6,7 +6,7 @@
  */
 
 import { compare, defaultSortRow, sortRows } from '../sorting';
-import { sortStates } from '../../state/sorting';
+import { sortStates } from '../../state/sortStates';
 
 describe('sortRows', () => {
   const rowIds = ['row2', 'row1'];

packages/react/src/components/DataTable/tools/__tests__/sorting-test.js

@@ -52,6 +52,8 @@ interface Cell {
   value: any;
 }
 
+// TODO: Should `SortRowParams` in
+// packages/react/src/components/DataTable/state/sorting.ts be used here?
 interface SortRowParams {
   key: string;
   sortDirection: DataTableSortState;