JSDocs for sort feature

Signed-off-by: Mike Turley <[email protected]>

client/src/app/hooks/table-controls/filtering/getFilterHubRequestParams.ts

@@ -172,7 +172,8 @@ export const serializeFilterForHub = (filter: HubFilter): string => {
 };
 
 /**
- * Converts all HubFilter values to URL query strings and appends them to the given `serializedParams` object for use in the hub API request
+ * Converts the values returned by getFilterHubRequestParams into the URL query strings expected by the hub API
+ * - Appends converted URL params to the given `serializedParams` object for use in the hub API request
  * - Constructs part of the object returned by serializeRequestParamsForHub
  * @see serializeRequestParamsForHub
  */

client/src/app/hooks/table-controls/pagination/getLocalPaginationDerivedState.ts

@@ -9,7 +9,7 @@ import { IPaginationState } from "./usePaginationState";
  */
 export interface ILocalPaginationDerivedStateArgs<TItem> {
   /**
-   * The API data items before pagination
+   * The API data items before pagination (but after filtering)
    */
   items: TItem[];
   /**

client/src/app/hooks/table-controls/pagination/getPaginationHubRequestParams.ts

@@ -25,6 +25,12 @@ export const getPaginationHubRequestParams = ({
   return { page: { pageNumber, itemsPerPage } };
 };
 
+/**
+ * Converts the values returned by getPaginationHubRequestParams into the URL query strings expected by the hub API
+ * - Appends converted URL params to the given `serializedParams` object for use in the hub API request
+ * - Constructs part of the object returned by serializeRequestParamsForHub
+ * @see serializeRequestParamsForHub
+ */
 export const serializePaginationRequestParamsForHub = (
   deserializedParams: HubRequestParams,
   serializedParams: URLSearchParams

client/src/app/hooks/table-controls/pagination/usePaginationPropHelpers.ts

@@ -44,6 +44,9 @@ export const usePaginationPropHelpers = (
 
   usePaginationEffects(args);
 
+  /**
+   * Props for the PF Pagination component
+   */
   const paginationProps: PaginationProps = {
     itemCount: totalItemCount,
     perPage: itemsPerPage,
@@ -55,6 +58,9 @@ export const usePaginationPropHelpers = (
     },
   };
 
+  /**
+   * Props for the PF ToolbarItem component which contains the Pagination component
+   */
   const paginationToolbarItemProps: ToolbarItemProps = {
     variant: "pagination",
     align: { default: "alignRight" },

client/src/app/hooks/table-controls/pagination/usePaginationState.ts

@@ -2,6 +2,9 @@ import { usePersistentState } from "@app/hooks/usePersistentState";
 import { IFeaturePersistenceArgs } from "../types";
 import { DiscriminatedArgs } from "@app/utils/type-utils";
 
+/**
+ * The currently applied pagination parameters
+ */
 export interface IActivePagination {
   /**
    * The current page number on the user's pagination controls (counting from 1)

client/src/app/hooks/table-controls/sorting/getLocalSortDerivedState.ts

@@ -1,17 +1,42 @@
 import i18n from "@app/i18n";
 import { ISortState } from "./useSortState";
 
+/**
+ * Args for getLocalSortDerivedState
+ * - Partially satisfied by the object returned by useTableControlState (ITableControlState)
+ * - Makes up part of the arguments object taken by getLocalTableControlDerivedState (ITableControlLocalDerivedStateArgs)
+ * @see ITableControlState
+ * @see ITableControlLocalDerivedStateArgs
+ */
 export interface ILocalSortDerivedStateArgs<
   TItem,
   TSortableColumnKey extends string,
 > {
+  /**
+   * The API data items before sorting
+   */
   items: TItem[];
+  /**
+   * A callback function to return, for a given API data item, a record of sortable primitives for that item's sortable columns
+   * - The record maps:
+   *   - from `columnKey` values (the keys of the `columnNames` object passed to useTableControlState)
+   *   - to easily sorted primitive values (string | number | boolean) for this item's value in that column
+   */
   getSortValues?: (
+    // TODO can we require this as non-optional in types that extend this when we know we're configuring a client-computed table?
     item: TItem
   ) => Record<TSortableColumnKey, string | number | boolean>;
+  /**
+   * The "source of truth" state for the sort feature (returned by useSortState)
+   */
   sortState: ISortState<TSortableColumnKey>;
 }
 
+/**
+ * Given the "source of truth" state for the sort feature and additional arguments, returns "derived state" values and convenience functions.
+ * - For local/client-computed tables only. Performs the actual sorting logic, which is done on the server for server-computed tables.
+ * - "source of truth" (persisted) state and "derived state" are kept separate to prevent out-of-sync duplicated state.
+ */
 export const getLocalSortDerivedState = <
   TItem,
   TSortableColumnKey extends string,

client/src/app/hooks/table-controls/sorting/getSortHubRequestParams.ts

@@ -1,13 +1,29 @@
 import { HubRequestParams } from "@app/api/models";
 import { ISortState } from "./useSortState";
 
+/**
+ * Args for getSortHubRequestParams
+ * - Partially satisfied by the object returned by useTableControlState (ITableControlState)
+ */
 export interface IGetSortHubRequestParamsArgs<
   TSortableColumnKey extends string,
 > {
+  /**
+   * The "source of truth" state for the sort feature (returned by usePaginationState)
+   */
   sortState?: ISortState<TSortableColumnKey>;
+  /**
+   * A map of `columnKey` values (keys of the `columnNames` object passed to useTableControlState) to the field keys used by the hub API for sorting on those columns
+   * - Keys and values in this object will usually be the same, but sometimes we need to present a hub field with a different name/key or have a column that is a composite of multiple hub fields.
+   */
   hubSortFieldKeys?: Record<TSortableColumnKey, string>;
 }
 
+/**
+ * Given the state for the sort feature and additional arguments, returns params the hub API needs to apply the current sort.
+ * - Makes up part of the object returned by getHubRequestParams
+ * @see getHubRequestParams
+ */
 export const getSortHubRequestParams = <TSortableColumnKey extends string>({
   sortState,
   hubSortFieldKeys,
@@ -22,6 +38,12 @@ export const getSortHubRequestParams = <TSortableColumnKey extends string>({
   };
 };
 
+/**
+ * Converts the values returned by getSortHubRequestParams into the URL query strings expected by the hub API
+ * - Appends converted URL params to the given `serializedParams` object for use in the hub API request
+ * - Constructs part of the object returned by serializeRequestParamsForHub
+ * @see serializeRequestParamsForHub
+ */
 export const serializeSortRequestParamsForHub = (
   deserializedParams: HubRequestParams,
   serializedParams: URLSearchParams

client/src/app/hooks/table-controls/sorting/useSortPropHelpers.ts

@@ -1,20 +1,44 @@
 import { ThProps } from "@patternfly/react-table";
 import { ISortState } from "./useSortState";
 
-// Args that should be passed into useTableControlProps
+/**
+ * Args for useSortPropHelpers that come from outside useTableControlProps
+ * - Partially satisfied by the object returned by useTableControlState (ITableControlState)
+ * - Makes up part of the arguments object taken by useTableControlProps (IUseTableControlPropsArgs)
+ * @see ITableControlState
+ * @see IUseTableControlPropsArgs
+ */
 export interface ISortPropHelpersExternalArgs<
   TColumnKey extends string,
   TSortableColumnKey extends TColumnKey,
 > {
+  /**
+   * The "source of truth" state for the sort feature (returned by useSortState)
+   */
   sortState: ISortState<TSortableColumnKey>;
+  /**
+   * The `columnKey` values (keys of the `columnNames` object passed to useTableControlState) corresponding to columns with sorting enabled
+   */
   sortableColumns?: TSortableColumnKey[];
 }
 
-// Additional args that come from logic inside useTableControlProps
+/**
+ * Additional args for useSortPropHelpers that come from logic inside useTableControlProps
+ * @see useTableControlProps
+ */
 export interface ISortPropHelpersInternalArgs<TColumnKey extends string> {
+  /**
+   * The keys of the `columnNames` object passed to useTableControlState (for all columns, not just the sortable ones)
+   */
   columnKeys: TColumnKey[];
 }
 
+/**
+ * Returns derived state and prop helpers for the sort feature based on given "source of truth" state.
+ * - Used internally by useTableControlProps
+ * - "Derived state" here refers to values and convenience functions derived at render time.
+ * - "source of truth" (persisted) state and "derived state" are kept separate to prevent out-of-sync duplicated state.
+ */
 export const useSortPropHelpers = <
   TColumnKey extends string,
   TSortableColumnKey extends TColumnKey,
@@ -28,6 +52,9 @@ export const useSortPropHelpers = <
     columnKeys,
   } = args;
 
+  /**
+   * Returns props for the Th component for a column with sorting enabled.
+   */
   const getSortThProps = ({
     columnKey,
   }: {

client/src/app/hooks/table-controls/sorting/useSortState.ts

@@ -2,25 +2,68 @@ import { DiscriminatedArgs } from "@app/utils/type-utils";
 import { IFeaturePersistenceArgs } from "..";
 import { usePersistentState } from "@app/hooks/usePersistentState";
 
+/**
+ * The currently applied sort parameters
+ */
 export interface IActiveSort<TSortableColumnKey extends string> {
+  /**
+   * The identifier for the currently sorted column (`columnKey` values come from the keys of the `columnNames` object passed to useTableControlState)
+   */
   columnKey: TSortableColumnKey;
+  /**
+   * The direction of the currently applied sort (ascending or descending)
+   */
   direction: "asc" | "desc";
 }
 
+/**
+ * The "source of truth" state for the sort feature.
+ * - Included in the object returned by useTableControlState (ITableControlState) under the `sortState` property.
+ * - Also included in the `ITableControls` object returned by useTableControlProps and useLocalTableControls.
+ * @see ITableControlState
+ * @see ITableControls
+ */
 export interface ISortState<TSortableColumnKey extends string> {
+  /**
+   * The currently applied sort column and direction
+   */
   activeSort: IActiveSort<TSortableColumnKey> | null;
+  /**
+   * Updates the currently applied sort column and direction
+   */
   setActiveSort: (sort: IActiveSort<TSortableColumnKey>) => void;
 }
 
+/**
+ * Args for useSortState
+ * - Makes up part of the arguments object taken by useTableControlState (IUseTableControlStateArgs)
+ * - The properties defined here are only required by useTableControlState if isSortEnabled is true (see DiscriminatedArgs)
+ * - Properties here are included in the `ITableControls` object returned by useTableControlProps and useLocalTableControls.
+ * @see IUseTableControlStateArgs
+ * @see DiscriminatedArgs
+ * @see ITableControls
+ */
 export type ISortStateArgs<TSortableColumnKey extends string> =
   DiscriminatedArgs<
     "isSortEnabled",
     {
+      /**
+       * The `columnKey` values (keys of the `columnNames` object passed to useTableControlState) corresponding to columns with sorting enabled
+       */
       sortableColumns: TSortableColumnKey[];
+      /**
+       * The sort column and direction that should be applied by default when the table first loads
+       */
       initialSort?: IActiveSort<TSortableColumnKey> | null;
     }
   >;
 
+/**
+ * Provides the "source of truth" state for the sort feature.
+ * - Used internally by useTableControlState
+ * - Takes args defined above as well as optional args for persisting state to a configurable storage target.
+ * @see PersistTarget
+ */
 export const useSortState = <
   TSortableColumnKey extends string,
   TPersistenceKeyPrefix extends string = string,