feat(Datagrid): add option to specify an initial sortable column (#4423)

* feat(Datagrid): apply initial column sort functionality

* fix: return if not using sortable table

packages/ibm-products/src/components/Datagrid/Datagrid.docs-page.js

@@ -436,6 +436,42 @@ const datagridState = useDatagrid(
   useSortableColumns
 );
 
+return <Datagrid datagridState={datagridState} />;
+          `,
+        },
+      },
+      {
+        description: `Columns can also be initially sorted by providing a \`sortableColumn\` object to the \`initialState\`. The structure of
+        the \`sortableColumn\` property is as follows:
+\`
+{
+  id: string, // column id
+  order: string, // ASC | DESC
+}
+\`
+
+See example below: `,
+        source: {
+          code: `
+const [data] = useState(makeData(10));
+const columns = React.useMemo(() => getColumns(data), []);
+const datagridState = useDatagrid(
+  {
+    columns,
+    data,
+    ascendingSortableLabelText: 'none',
+    descendingSortableLabelText: 'ascending',
+    defaultSortableLabelText: 'descending',
+    initialState: {
+      sortableColumn: {
+        id: 'firstName', // column id
+        order: 'ASC' // sorting order
+      }
+    }
+  },
+  useSortableColumns
+);
+
 return <Datagrid datagridState={datagridState} />;
           `,
         },

packages/ibm-products/src/components/Datagrid/Datagrid.stories.js

@@ -354,11 +354,17 @@ export const SortableColumns = () => {
       ascendingSortableLabelText: 'ascending',
       descendingSortableLabelText: 'descending',
       defaultSortableLabelText: 'none',
+      initialState: {
+        sortableColumn: {
+          id: 'firstName',
+          order: 'ASC',
+        },
+      },
     },
     useSortableColumns
   );
 
-  return <Datagrid datagridState={{ ...datagridState }} />;
+  return <Datagrid datagridState={datagridState} />;
 };
 
 export const ActionsDropdown = () => {

packages/ibm-products/src/components/Datagrid/Datagrid/DatagridHeaderRow.js

@@ -18,6 +18,7 @@ import {
 } from './addons/stateReducer';
 import { getNodeTextContent } from '../../../global/js/utils/getNodeTextContent';
 import { DatagridSlug } from './addons/Slug/DatagridSlug';
+import { useInitialColumnSort } from '../useInitialColumnSort';
 
 const blockClass = `${pkg.prefix}--datagrid`;
 
@@ -100,6 +101,7 @@ const ResizeHeader = ({
 
 const HeaderRow = (datagridState, headRef, headerGroup) => {
   const { resizerAriaLabel, isTableSortable, rows, isFetching } = datagridState;
+  useInitialColumnSort(datagridState);
   // Used to measure the height of the table and uses that value
   // to display a vertical line to indicate the column you are resizing
   useEffect(() => {

packages/ibm-products/src/components/Datagrid/useInitialColumnSort.js

@@ -0,0 +1,29 @@
+/**
+ * Copyright IBM Corp. 2024, 2024
+ *
+ * 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 { useEffect, useState } from 'react';
+import { getNewSortOrder } from './useSortableColumns';
+
+export const useInitialColumnSort = (instance) => {
+  const [hasInitialSort, setHasInitialSort] = useState(false);
+  useEffect(() => {
+    const { initialState, headers, onSort, isTableSortable } = instance;
+    const { sortableColumn } = initialState;
+    const foundSortedCol = headers.some((h) => h.isSorted);
+    if (foundSortedCol || hasInitialSort || !isTableSortable) {
+      return;
+    }
+
+    if (sortableColumn) {
+      const { id: columnId, order } = sortableColumn;
+      const { newSortDesc, newOrder } = getNewSortOrder(order);
+      onSort?.(columnId, newOrder);
+      instance.toggleSortBy(columnId, newSortDesc, false);
+      setHasInitialSort(true);
+    }
+  }, [instance, hasInitialSort]);
+};

packages/ibm-products/src/components/Datagrid/useSortableColumns.js

@@ -21,6 +21,22 @@ const ordering = {
   NONE: 'NONE',
 };
 
+export const getNewSortOrder = (sortOrder) => {
+  const order = {
+    newSortDesc: undefined,
+    newOrder: ordering.NONE,
+  };
+  if (sortOrder === false || sortOrder === ordering.DESC) {
+    order.newOrder = ordering.DESC;
+    order.newSortDesc = true;
+  }
+  if (sortOrder === undefined || sortOrder === ordering.ASC) {
+    order.newOrder = ordering.ASC;
+    order.newSortDesc = false;
+  }
+  return order;
+};
+
 const getAriaSortValue = (
   col,
   {
@@ -160,21 +176,6 @@ const useSortableColumns = (hooks) => {
     Object.assign(instance, { manualSortBy: !!onSort, isTableSortable: true });
   };
 
-  const getNewSortOrder = (sortOrder) => {
-    const order = {
-      newSortDesc: undefined,
-      newOrder: ordering.NONE,
-    };
-    if (sortOrder === false) {
-      order.newOrder = ordering.DESC;
-      order.newSortDesc = true;
-    }
-    if (sortOrder === undefined) {
-      order.newOrder = ordering.ASC;
-      order.newSortDesc = false;
-    }
-    return order;
-  };
   hooks.visibleColumns.push(sortableVisibleColumns);
   hooks.useInstance.push(sortInstanceProps);
 };