From 44bca551553b808526ff112b295328457a076b44 Mon Sep 17 00:00:00 2001
From: John Hooks <bitmachina@outlook.com>
Date: Wed, 15 May 2024 02:53:09 -0700
Subject: [PATCH] fix: improve dataview types (#61586)

This commit improves the types in the dataviews package.

This is helpful by typing the `item` or `items` provided as arguments
to the functions of the fields and actions of the `DataViews`.

This commit does not implement requiring these types in the `DataView`
component, but helps to improve the types of the functions that are
used in the `DataView` package. It also allows exporting the types
to be used in consumers of the package.

- Add generic item type to all dataview types that operate
on `item` or lists of `items`.

- Update the usage in the dataviews package to incorporate
the use of the generic item type.

Co-authored-by: johnhooks <bitmachina@git.wordpress.org>
Co-authored-by: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: sirreal <jonsurrell@git.wordpress.org>
---
 packages/dataviews/src/bulk-actions.tsx       | 55 +++++++-------
 .../src/filter-and-sort-data-view.ts          | 21 +++--
 packages/dataviews/src/item-actions.tsx       | 63 ++++++++-------
 packages/dataviews/src/normalize-fields.ts    |  6 +-
 .../src/single-selection-checkbox.tsx         | 12 +--
 packages/dataviews/src/types.ts               | 76 +++++++++++++------
 packages/dataviews/src/view-list.tsx          | 31 ++++----
 7 files changed, 159 insertions(+), 105 deletions(-)

diff --git a/packages/dataviews/src/bulk-actions.tsx b/packages/dataviews/src/bulk-actions.tsx
index 0e9d6f3134d389..f2bb80dc3292e4 100644
--- a/packages/dataviews/src/bulk-actions.tsx
+++ b/packages/dataviews/src/bulk-actions.tsx
@@ -13,7 +13,7 @@ import { useMemo, useState, useCallback, useEffect } from '@wordpress/element';
  * Internal dependencies
  */
 import { unlock } from './lock-unlock';
-import type { Action, ActionModal, Data, Item } from './types';
+import type { Action, ActionModal, AnyItem } from './types';
 
 const {
 	DropdownMenuV2: DropdownMenu,
@@ -22,34 +22,37 @@ const {
 	DropdownMenuSeparatorV2: DropdownMenuSeparator,
 } = unlock( componentsPrivateApis );
 
-interface ActionWithModalProps {
-	action: ActionModal;
+interface ActionWithModalProps< Item extends AnyItem > {
+	action: ActionModal< Item >;
 	selectedItems: Item[];
-	setActionWithModal: ( action?: ActionModal ) => void;
+	setActionWithModal: ( action?: ActionModal< Item > ) => void;
 	onMenuOpenChange: ( isOpen: boolean ) => void;
 }
 
-interface BulkActionsItemProps {
-	action: Action;
+interface BulkActionsItemProps< Item extends AnyItem > {
+	action: Action< Item >;
 	selectedItems: Item[];
-	setActionWithModal: ( action?: ActionModal ) => void;
+	setActionWithModal: ( action?: ActionModal< Item > ) => void;
 }
 
-interface ActionsMenuGroupProps {
-	actions: Action[];
+interface ActionsMenuGroupProps< Item extends AnyItem > {
+	actions: Action< Item >[];
 	selectedItems: Item[];
-	setActionWithModal: ( action?: ActionModal ) => void;
+	setActionWithModal: ( action?: ActionModal< Item > ) => void;
 }
 
-interface BulkActionsProps {
-	data: Data;
-	actions: Action[];
+interface BulkActionsProps< Item extends AnyItem > {
+	data: Item[];
+	actions: Action< Item >[];
 	selection: string[];
 	onSelectionChange: ( selection: Item[] ) => void;
 	getItemId: ( item: Item ) => string;
 }
 
-export function useHasAPossibleBulkAction( actions: Action[], item: Item ) {
+export function useHasAPossibleBulkAction< Item extends AnyItem >(
+	actions: Action< Item >[],
+	item: Item
+) {
 	return useMemo( () => {
 		return actions.some( ( action ) => {
 			return (
@@ -60,9 +63,9 @@ export function useHasAPossibleBulkAction( actions: Action[], item: Item ) {
 	}, [ actions, item ] );
 }
 
-export function useSomeItemHasAPossibleBulkAction(
-	actions: Action[],
-	data: Data
+export function useSomeItemHasAPossibleBulkAction< Item extends AnyItem >(
+	actions: Action< Item >[],
+	data: Item[]
 ) {
 	return useMemo( () => {
 		return data.some( ( item ) => {
@@ -76,12 +79,12 @@ export function useSomeItemHasAPossibleBulkAction(
 	}, [ actions, data ] );
 }
 
-function ActionWithModal( {
+function ActionWithModal< Item extends AnyItem >( {
 	action,
 	selectedItems,
 	setActionWithModal,
 	onMenuOpenChange,
-}: ActionWithModalProps ) {
+}: ActionWithModalProps< Item > ) {
 	const eligibleItems = useMemo( () => {
 		return selectedItems.filter(
 			( item ) => ! action.isEligible || action.isEligible( item )
@@ -107,11 +110,11 @@ function ActionWithModal( {
 	);
 }
 
-function BulkActionItem( {
+function BulkActionItem< Item extends AnyItem >( {
 	action,
 	selectedItems,
 	setActionWithModal,
-}: BulkActionsItemProps ) {
+}: BulkActionsItemProps< Item > ) {
 	const eligibleItems = useMemo( () => {
 		return selectedItems.filter(
 			( item ) => ! action.isEligible || action.isEligible( item )
@@ -141,11 +144,11 @@ function BulkActionItem( {
 	);
 }
 
-function ActionsMenuGroup( {
+function ActionsMenuGroup< Item extends AnyItem >( {
 	actions,
 	selectedItems,
 	setActionWithModal,
-}: ActionsMenuGroupProps ) {
+}: ActionsMenuGroupProps< Item > ) {
 	return (
 		<>
 			<DropdownMenuGroup>
@@ -163,20 +166,20 @@ function ActionsMenuGroup( {
 	);
 }
 
-export default function BulkActions( {
+export default function BulkActions< Item extends AnyItem >( {
 	data,
 	actions,
 	selection,
 	onSelectionChange,
 	getItemId,
-}: BulkActionsProps ) {
+}: BulkActionsProps< Item > ) {
 	const bulkActions = useMemo(
 		() => actions.filter( ( action ) => action.supportsBulk ),
 		[ actions ]
 	);
 	const [ isMenuOpen, onMenuOpenChange ] = useState( false );
 	const [ actionWithModal, setActionWithModal ] = useState<
-		ActionModal | undefined
+		ActionModal< Item > | undefined
 	>();
 	const selectableItems = useMemo( () => {
 		return data.filter( ( item ) => {
diff --git a/packages/dataviews/src/filter-and-sort-data-view.ts b/packages/dataviews/src/filter-and-sort-data-view.ts
index dcbff18045dc93..a2906fdc4869e3 100644
--- a/packages/dataviews/src/filter-and-sort-data-view.ts
+++ b/packages/dataviews/src/filter-and-sort-data-view.ts
@@ -15,13 +15,13 @@ import {
 	OPERATOR_IS_NOT_ALL,
 } from './constants';
 import { normalizeFields } from './normalize-fields';
-import type { Data, Field, View } from './types';
+import type { Field, AnyItem, View } from './types';
 
 function normalizeSearchInput( input = '' ) {
 	return removeAccents( input.trim().toLowerCase() );
 }
 
-const EMPTY_ARRAY: Data = [];
+const EMPTY_ARRAY: [] = [];
 
 /**
  * Applies the filtering, sorting and pagination to the raw data based on the view configuration.
@@ -32,11 +32,14 @@ const EMPTY_ARRAY: Data = [];
  *
  * @return Filtered, sorted and paginated data.
  */
-export function filterSortAndPaginate(
-	data: Data,
+export function filterSortAndPaginate< Item extends AnyItem >(
+	data: Item[],
 	view: View,
-	fields: Field[]
-): { data: Data; paginationInfo: { totalItems: number; totalPages: number } } {
+	fields: Field< Item >[]
+): {
+	data: Item[];
+	paginationInfo: { totalItems: number; totalPages: number };
+} {
 	if ( ! data ) {
 		return {
 			data: EMPTY_ARRAY,
@@ -100,7 +103,9 @@ export function filterSortAndPaginate(
 				) {
 					filteredData = filteredData.filter( ( item ) => {
 						return filter.value.every( ( value: any ) => {
-							return field.getValue( { item } ).includes( value );
+							return field
+								.getValue( { item } )
+								?.includes( value );
 						} );
 					} );
 				} else if (
@@ -111,7 +116,7 @@ export function filterSortAndPaginate(
 						return filter.value.every( ( value: any ) => {
 							return ! field
 								.getValue( { item } )
-								.includes( value );
+								?.includes( value );
 						} );
 					} );
 				} else if ( filter.operator === OPERATOR_IS ) {
diff --git a/packages/dataviews/src/item-actions.tsx b/packages/dataviews/src/item-actions.tsx
index cbf4cdc479d437..3b45561defdd68 100644
--- a/packages/dataviews/src/item-actions.tsx
+++ b/packages/dataviews/src/item-actions.tsx
@@ -20,7 +20,7 @@ import { moreVertical } from '@wordpress/icons';
  * Internal dependencies
  */
 import { unlock } from './lock-unlock';
-import type { Action, ActionModal as ActionModalType, Item } from './types';
+import type { Action, ActionModal as ActionModalType, AnyItem } from './types';
 
 const {
 	DropdownMenuV2: DropdownMenu,
@@ -30,46 +30,50 @@ const {
 	kebabCase,
 } = unlock( componentsPrivateApis );
 
-interface ButtonTriggerProps {
-	action: Action;
+interface ButtonTriggerProps< Item extends AnyItem > {
+	action: Action< Item >;
 	onClick: MouseEventHandler;
 }
 
-interface DropdownMenuItemTriggerProps {
-	action: Action;
+interface DropdownMenuItemTriggerProps< Item extends AnyItem > {
+	action: Action< Item >;
 	onClick: MouseEventHandler;
 }
 
-interface ActionModalProps {
-	action: ActionModalType;
+interface ActionModalProps< Item extends AnyItem > {
+	action: ActionModalType< Item >;
 	items: Item[];
 	closeModal?: () => void;
 }
 
-interface ActionWithModalProps extends ActionModalProps {
+interface ActionWithModalProps< Item extends AnyItem >
+	extends ActionModalProps< Item > {
 	ActionTrigger: (
-		props: ButtonTriggerProps | DropdownMenuItemTriggerProps
+		props: ButtonTriggerProps< Item > | DropdownMenuItemTriggerProps< Item >
 	) => ReactElement;
 	isBusy?: boolean;
 }
 
-interface ActionsDropdownMenuGroupProps {
-	actions: Action[];
+interface ActionsDropdownMenuGroupProps< Item extends AnyItem > {
+	actions: Action< Item >[];
 	item: Item;
 }
 
-interface ItemActionsProps {
+interface ItemActionsProps< Item extends AnyItem > {
 	item: Item;
-	actions: Action[];
+	actions: Action< Item >[];
 	isCompact: boolean;
 }
 
-interface CompactItemActionsProps {
+interface CompactItemActionsProps< Item extends AnyItem > {
 	item: Item;
-	actions: Action[];
+	actions: Action< Item >[];
 }
 
-function ButtonTrigger( { action, onClick }: ButtonTriggerProps ) {
+function ButtonTrigger< Item extends AnyItem >( {
+	action,
+	onClick,
+}: ButtonTriggerProps< Item > ) {
 	return (
 		<Button
 			label={ action.label }
@@ -81,10 +85,10 @@ function ButtonTrigger( { action, onClick }: ButtonTriggerProps ) {
 	);
 }
 
-function DropdownMenuItemTrigger( {
+function DropdownMenuItemTrigger< Item extends AnyItem >( {
 	action,
 	onClick,
-}: DropdownMenuItemTriggerProps ) {
+}: DropdownMenuItemTriggerProps< Item > ) {
 	return (
 		<DropdownMenuItem
 			onClick={ onClick }
@@ -95,7 +99,11 @@ function DropdownMenuItemTrigger( {
 	);
 }
 
-export function ActionModal( { action, items, closeModal }: ActionModalProps ) {
+export function ActionModal< Item extends AnyItem >( {
+	action,
+	items,
+	closeModal,
+}: ActionModalProps< Item > ) {
 	return (
 		<Modal
 			title={ action.modalHeader || action.label }
@@ -115,12 +123,12 @@ export function ActionModal( { action, items, closeModal }: ActionModalProps ) {
 	);
 }
 
-export function ActionWithModal( {
+export function ActionWithModal< Item extends AnyItem >( {
 	action,
 	items,
 	ActionTrigger,
 	isBusy,
-}: ActionWithModalProps ) {
+}: ActionWithModalProps< Item > ) {
 	const [ isModalOpen, setIsModalOpen ] = useState( false );
 	const actionTriggerProps = {
 		action,
@@ -144,10 +152,10 @@ export function ActionWithModal( {
 	);
 }
 
-export function ActionsDropdownMenuGroup( {
+export function ActionsDropdownMenuGroup< Item extends AnyItem >( {
 	actions,
 	item,
-}: ActionsDropdownMenuGroupProps ) {
+}: ActionsDropdownMenuGroupProps< Item > ) {
 	return (
 		<DropdownMenuGroup>
 			{ actions.map( ( action ) => {
@@ -173,11 +181,11 @@ export function ActionsDropdownMenuGroup( {
 	);
 }
 
-export default function ItemActions( {
+export default function ItemActions< Item extends AnyItem >( {
 	item,
 	actions,
 	isCompact,
-}: ItemActionsProps ) {
+}: ItemActionsProps< Item > ) {
 	const { primaryActions, eligibleActions } = useMemo( () => {
 		// If an action is eligible for all items, doesn't need
 		// to provide the `isEligible` function.
@@ -230,7 +238,10 @@ export default function ItemActions( {
 	);
 }
 
-function CompactItemActions( { item, actions }: CompactItemActionsProps ) {
+function CompactItemActions< Item extends AnyItem >( {
+	item,
+	actions,
+}: CompactItemActionsProps< Item > ) {
 	return (
 		<DropdownMenu
 			trigger={
diff --git a/packages/dataviews/src/normalize-fields.ts b/packages/dataviews/src/normalize-fields.ts
index 8745a1b3316bc5..2c5edd91070c7d 100644
--- a/packages/dataviews/src/normalize-fields.ts
+++ b/packages/dataviews/src/normalize-fields.ts
@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import type { Field, NormalizedField } from './types';
+import type { Field, AnyItem, NormalizedField } from './types';
 
 /**
  * Apply default values and normalize the fields config.
@@ -9,7 +9,9 @@ import type { Field, NormalizedField } from './types';
  * @param fields Fields config.
  * @return Normalized fields config.
  */
-export function normalizeFields( fields: Field[] ): NormalizedField[] {
+export function normalizeFields< Item extends AnyItem >(
+	fields: Field< Item >[]
+): NormalizedField< Item >[] {
 	return fields.map( ( field ) => {
 		const getValue = field.getValue || ( ( { item } ) => item[ field.id ] );
 
diff --git a/packages/dataviews/src/single-selection-checkbox.tsx b/packages/dataviews/src/single-selection-checkbox.tsx
index aad77161359efb..1c87c7f7c52c17 100644
--- a/packages/dataviews/src/single-selection-checkbox.tsx
+++ b/packages/dataviews/src/single-selection-checkbox.tsx
@@ -7,19 +7,19 @@ import { CheckboxControl } from '@wordpress/components';
 /**
  * Internal dependencies
  */
-import type { Data, Field, Item } from './types';
+import type { Field, AnyItem } from './types';
 
-interface SingleSelectionCheckboxProps {
+interface SingleSelectionCheckboxProps< Item extends AnyItem > {
 	selection: string[];
 	onSelectionChange: ( selection: Item[] ) => void;
 	item: Item;
-	data: Data;
+	data: Item[];
 	getItemId: ( item: Item ) => string;
-	primaryField?: Field;
+	primaryField?: Field< Item >;
 	disabled: boolean;
 }
 
-export default function SingleSelectionCheckbox( {
+export default function SingleSelectionCheckbox< Item extends AnyItem >( {
 	selection,
 	onSelectionChange,
 	item,
@@ -27,7 +27,7 @@ export default function SingleSelectionCheckbox( {
 	getItemId,
 	primaryField,
 	disabled,
-}: SingleSelectionCheckboxProps ) {
+}: SingleSelectionCheckboxProps< Item > ) {
 	const id = getItemId( item );
 	const isSelected = selection.includes( id );
 	let selectionLabel;
diff --git a/packages/dataviews/src/types.ts b/packages/dataviews/src/types.ts
index 7c367aace07ba2..18cc819e392cb4 100644
--- a/packages/dataviews/src/types.ts
+++ b/packages/dataviews/src/types.ts
@@ -3,21 +3,39 @@
  */
 import type { ReactElement, ReactNode } from 'react';
 
-interface Option {
-	value: any;
+export type SortDirection = 'asc' | 'desc';
+
+/**
+ * Generic option type.
+ */
+interface Option< Value extends any = any > {
+	value: Value;
 	label: string;
 }
 
-interface filterByConfig {
+interface FilterByConfig {
+	/**
+	 * The list of operators supported by the field.
+	 */
 	operators?: Operator[];
+
+	/**
+	 * Whether it is a primary filter.
+	 *
+	 * A primary filter is always visible and is not listed in the "Add filter" component,
+	 * except for the list layout where it behaves like a secondary filter.
+	 */
 	isPrimary?: boolean;
 }
 
 type Operator = 'is' | 'isNot' | 'isAny' | 'isNone' | 'isAll' | 'isNotAll';
 
-export type Item = Record< string, any >;
+export type AnyItem = Record< string, any >;
 
-export interface Field {
+/**
+ * A dataview field for a specific property of a data type.
+ */
+export interface Field< Item extends AnyItem > {
 	/**
 	 * The unique identifier of the field.
 	 */
@@ -32,58 +50,67 @@ export interface Field {
 	 * Callback used to retrieve the value of the field from the item.
 	 * Defaults to `item[ field.id ]`.
 	 */
-	getValue?: ( { item }: { item: Item } ) => any;
+	getValue?: ( args: { item: Item } ) => any;
 
 	/**
 	 * Callback used to render the field. Defaults to `field.getValue`.
 	 */
-	render?: ( { item }: { item: Item } ) => ReactNode;
+	render?: ( args: { item: Item } ) => ReactNode;
 
 	/**
 	 * The width of the field column.
 	 */
-	width: string | number | undefined;
+	width?: string | number;
 
 	/**
 	 * The minimum width of the field column.
 	 */
-	maxWidth: string | number | undefined;
+	maxWidth?: string | number;
 
 	/**
 	 * The maximum width of the field column.
 	 */
-	minWidth: string | number | undefined;
+	minWidth?: string | number;
 
 	/**
 	 * Whether the field is sortable.
 	 */
-	enableSorting: boolean | undefined;
+	enableSorting?: boolean;
 
 	/**
 	 * Whether the field is searchable.
 	 */
-	enableGlobalSearch: boolean | undefined;
+	enableGlobalSearch?: boolean;
 
 	/**
 	 * Whether the field is filterable.
 	 */
-	enableHiding: boolean | undefined;
+	enableHiding?: boolean;
 
 	/**
 	 * The list of options to pick from when using the field as a filter.
 	 */
-	elements: Option[] | undefined;
+	elements?: Option[];
 
 	/**
 	 * Filter config for the field.
 	 */
-	filterBy: filterByConfig | undefined;
+	filterBy?: FilterByConfig | undefined;
 }
 
-export type NormalizedField = Required< Field >;
+export type NormalizedField< Item extends AnyItem > = Field< Item > &
+	Required< Pick< Field< Item >, 'header' | 'getValue' | 'render' > >;
+
+/**
+ * A collection of dataview fields for a data type.
+ */
+export type Fields< Item extends AnyItem > = Field< Item >[];
 
-export type Data = Item[];
+export type Data< Item extends AnyItem > = Item[];
 
+/**
+ * The filters applied to the dataset.
+ */
 export interface Filter {
 	/**
 	 * The field to filter by.
@@ -129,7 +156,7 @@ interface ViewBase {
 		/**
 		 * The direction to sort by.
 		 */
-		direction: string;
+		direction: SortDirection;
 	};
 
 	/**
@@ -147,6 +174,7 @@ interface ViewBase {
 	 */
 	hiddenFields: string[];
 }
+
 export interface ViewList extends ViewBase {
 	type: 'list';
 
@@ -165,7 +193,7 @@ export interface ViewList extends ViewBase {
 
 export type View = ViewList | ViewBase;
 
-interface ActionBase {
+interface ActionBase< Item extends AnyItem > {
 	/**
 	 * The unique identifier of the action.
 	 */
@@ -209,7 +237,8 @@ interface ActionBase {
 	supportsBulk?: boolean;
 }
 
-export interface ActionModal extends ActionBase {
+export interface ActionModal< Item extends AnyItem >
+	extends ActionBase< Item > {
 	/**
 	 * The callback to execute when the action has finished.
 	 */
@@ -246,11 +275,14 @@ export interface ActionModal extends ActionBase {
 	modalHeader?: string;
 }
 
-export interface ActionButton extends ActionBase {
+export interface ActionButton< Item extends AnyItem >
+	extends ActionBase< AnyItem > {
 	/**
 	 * The callback to execute when the action is triggered.
 	 */
 	callback: ( items: Item[] ) => void;
 }
 
-export type Action = ActionModal | ActionButton;
+export type Action< Item extends AnyItem > =
+	| ActionModal< Item >
+	| ActionButton< Item >;
diff --git a/packages/dataviews/src/view-list.tsx b/packages/dataviews/src/view-list.tsx
index faf2d521b1e294..12d9a7f86008d7 100644
--- a/packages/dataviews/src/view-list.tsx
+++ b/packages/dataviews/src/view-list.tsx
@@ -34,18 +34,17 @@ import { moreVertical } from '@wordpress/icons';
 import { unlock } from './lock-unlock';
 import type {
 	Action,
-	Data,
-	Item,
+	AnyItem,
 	NormalizedField,
 	ViewList as ViewListType,
 } from './types';
 
 import { ActionsDropdownMenuGroup, ActionModal } from './item-actions';
 
-interface ListViewProps {
-	actions: Action[];
-	data: Data;
-	fields: NormalizedField[];
+interface ListViewProps< Item extends AnyItem > {
+	actions: Action< Item >[];
+	data: Item[];
+	fields: NormalizedField< Item >[];
 	getItemId: ( item: Item ) => string;
 	id: string;
 	isLoading: boolean;
@@ -54,16 +53,16 @@ interface ListViewProps {
 	view: ViewListType;
 }
 
-interface ListViewItemProps {
-	actions: Action[];
+interface ListViewItemProps< Item extends AnyItem > {
+	actions: Action< Item >[];
 	id?: string;
 	isSelected: boolean;
 	item: Item;
-	mediaField?: NormalizedField;
+	mediaField?: NormalizedField< Item >;
 	onSelect: ( item: Item ) => void;
-	primaryField?: NormalizedField;
+	primaryField?: NormalizedField< Item >;
 	store: CompositeStore;
-	visibleFields: NormalizedField[];
+	visibleFields: NormalizedField< Item >[];
 }
 
 const {
@@ -74,7 +73,7 @@ const {
 	DropdownMenuV2: DropdownMenu,
 } = unlock( componentsPrivateApis );
 
-function ListItem( {
+function ListItem< Item extends AnyItem >( {
 	actions,
 	id,
 	isSelected,
@@ -84,7 +83,7 @@ function ListItem( {
 	primaryField,
 	store,
 	visibleFields,
-}: ListViewItemProps ) {
+}: ListViewItemProps< Item > ) {
 	const itemRef = useRef< HTMLElement >( null );
 	const labelId = `${ id }-label`;
 	const descriptionId = `${ id }-description`;
@@ -223,7 +222,7 @@ function ListItem( {
 									}
 								>
 									{ isModalOpen && (
-										<ActionModal
+										<ActionModal< Item >
 											action={ primaryAction }
 											items={ [ item ] }
 											closeModal={ () =>
@@ -311,7 +310,9 @@ function ListItem( {
 	);
 }
 
-export default function ViewList( props: ListViewProps ) {
+export default function ViewList< Item extends AnyItem >(
+	props: ListViewProps< Item >
+) {
 	const {
 		actions,
 		data,