feat: add example and docs for sorting hook

Author: fhlavac

packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md

@@ -16,7 +16,7 @@ sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/mod
 ---
 import { useMemo } from 'react';
 import { BrowserRouter, useSearchParams } from 'react-router-dom';
-import { useDataViewPagination, useDataViewSelection, useDataViewFilters } from '@patternfly/react-data-view/dist/dynamic/Hooks';
+import { useDataViewPagination, useDataViewSelection, useDataViewFilters, useDataViewSort } from '@patternfly/react-data-view/dist/dynamic/Hooks';
 import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView';
 import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect';
 import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar';
@@ -117,3 +117,34 @@ This example demonstrates the setup and usage of filters within the data view. I
 ```js file="./FiltersExample.tsx"
 
 ```
+
+### Sort state
+
+The `useDataViewSort` hook manages the sorting state of a data view. It provides an easy way to handle sorting logic, including synchronization with URL parameters and defining default sorting behavior.
+
+**Initial values:**
+- `initialSort` object to set default `sortBy` and `direction` values:
+  - `sortBy`: key of the initial column to sort.
+  - `direction`: default sorting direction (`asc` or `desc`).
+- Optional `searchParams` object to manage URL-based synchronization of sort state.
+- Optional `setSearchParams` function to update the URL parameters when sorting changes.
+- `defaultDirection` to set the default direction when no direction is specified.
+- Customizable parameter names for the URL:
+  - `sortByParam`: name of the URL parameter for the column key.
+  - `directionParam`: name of the URL parameter for the sorting direction.
+
+The `useDataViewSort` hook integrates seamlessly with React Router to manage sort state via URL parameters. Alternatively, you can use `URLSearchParams` and `window.history.pushState` APIs, or other routing libraries. If URL synchronization is not configured, the sort state is managed internally within the component.
+
+**Return values:**
+- `sortBy`: key of the column currently being sorted.
+- `direction`: current sorting direction (`asc` or `desc`).
+- `onSort`: function to handle sorting changes programmatically or via user interaction.
+
+### Sorting example
+
+This example demonstrates how to set up and use sorting functionality within a data view. The implementation includes dynamic sorting by column with persistence of sort state in the URL using React Router.
+
+
+```js file="./SortingExample.tsx"
+
+```

packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/SortingExample.tsx

@@ -0,0 +1,87 @@
+/* eslint-disable no-nested-ternary */
+import React, { useMemo } from 'react';
+import { useDataViewSort } from '@patternfly/react-data-view/dist/dynamic/Hooks';
+import { DataViewTable, DataViewTr, DataViewTh } from '@patternfly/react-data-view/dist/dynamic/DataViewTable';
+import { ThProps } from '@patternfly/react-table';
+import { BrowserRouter, useSearchParams } from 'react-router-dom';
+
+interface Repository {
+  name: string;
+  branches: string;
+  prs: string;
+  workspaces: string;
+  lastCommit: string;
+};
+
+const COLUMNS = [
+  { label: 'Repository', key: 'name', index: 0 },
+  { label: 'Branch', key: 'branches', index: 1 },
+  { label: 'Pull request', key: 'prs', index: 2 },
+  { label: 'Workspace', key: 'workspaces', index: 3 },
+  { label: 'Last commit', key: 'lastCommit', index: 4 }
+];
+
+const repositories: Repository[] = [
+  { name: 'Repository one', branches: 'Branch one', prs: 'Pull request one', workspaces: 'Workspace one', lastCommit: 'Timestamp one' },
+  { name: 'Repository two', branches: 'Branch two', prs: 'Pull request two', workspaces: 'Workspace two', lastCommit: 'Timestamp two' },
+  { name: 'Repository three', branches: 'Branch three', prs: 'Pull request three', workspaces: 'Workspace three', lastCommit: 'Timestamp three' },
+  { name: 'Repository four', branches: 'Branch four', prs: 'Pull request four', workspaces: 'Workspace four', lastCommit: 'Timestamp four' },
+  { name: 'Repository five', branches: 'Branch five', prs: 'Pull request five', workspaces: 'Workspace five', lastCommit: 'Timestamp five' },
+  { name: 'Repository six', branches: 'Branch six', prs: 'Pull request six', workspaces: 'Workspace six', lastCommit: 'Timestamp six' }
+];
+
+const sortData = (data: Repository[], sortBy: string | undefined, direction: 'asc' | 'desc' | undefined) =>
+  sortBy && direction
+    ? [ ...data ].sort((a, b) =>
+      direction === 'asc'
+        ? a[sortBy] < b[sortBy] ? -1 : a[sortBy] > b[sortBy] ? 1 : 0
+        : a[sortBy] > b[sortBy] ? -1 : a[sortBy] < b[sortBy] ? 1 : 0
+    )
+    : data;
+
+const ouiaId = 'TableExample';
+
+export const MyTable: React.FunctionComponent = () => {
+  const [ searchParams, setSearchParams ] = useSearchParams();
+  const { sortBy, direction, onSort } = useDataViewSort({ searchParams, setSearchParams });
+  const sortByIndex = useMemo(() => COLUMNS.findIndex(item => item.key === sortBy), [ sortBy ]);
+
+  const getSortParams = (columnIndex: number): ThProps['sort'] => ({
+    sortBy: {
+      index: sortByIndex,
+      direction,
+      defaultDirection: 'asc'
+    },
+    onSort: (_event, index, direction) => onSort(_event, COLUMNS[index].key, direction),
+    columnIndex
+  });
+
+  const columns: DataViewTh[] = COLUMNS.map((column, index) => ({
+    cell: column.label,
+    props: { sort: getSortParams(index) }
+  }));
+
+  const rows: DataViewTr[] = useMemo(() => sortData(repositories, sortBy, direction).map(({ name, branches, prs, workspaces, lastCommit }) => [
+    name,
+    branches,
+    prs,
+    workspaces,
+    lastCommit,
+  ]), [ sortBy, direction ]);
+
+  return (
+    <DataViewTable
+      aria-label="Repositories table"
+      ouiaId={ouiaId}
+      columns={columns}
+      rows={rows}
+    />
+  );
+};
+
+export const BasicExample: React.FunctionComponent = () => (
+  <BrowserRouter>
+    <MyTable/>
+  </BrowserRouter>
+)
+