@wordpress/dataviews 1.1.0 → 2.0.0

package/src/types.ts

@@ -1,23 +1,48 @@
 /**
  * External dependencies
  */
-import type { ReactNode } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 
-type Item = Record< string, any >;
+export type SortDirection = 'asc' | 'desc';
 
-interface Option {
-	value: any;
+/**
+ * Generic option type.
+ */
+export interface Option< Value extends any = any > {
+	value: Value;
 	label: string;
+	description?: 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 Operator =
+	| 'is'
+	| 'isNot'
+	| 'isAny'
+	| 'isNone'
+	| 'isAll'
+	| 'isNotAll';
+
+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 +57,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.
@@ -101,7 +135,44 @@ export interface Filter {
 	value: any;
 }
 
-export interface View {
+export interface NormalizedFilter {
+	/**
+	 * The field to filter by.
+	 */
+	field: string;
+
+	/**
+	 * The field name.
+	 */
+	name: string;
+
+	/**
+	 * The list of options to pick from when using the field as a filter.
+	 */
+	elements: Option[];
+
+	/**
+	 * Is a single selection filter.
+	 */
+	singleSelection: boolean;
+
+	/**
+	 * The list of operators supported by the field.
+	 */
+	operators: Operator[];
+
+	/**
+	 * Whether the filter is visible.
+	 */
+	isVisible: boolean;
+
+	/**
+	 * Whether it is a primary filter.
+	 */
+	isPrimary: boolean;
+}
+
+interface ViewBase {
 	/**
 	 * The layout of the view.
 	 */
@@ -129,7 +200,7 @@ export interface View {
 		/**
 		 * The direction to sort by.
 		 */
-		direction: string;
+		direction: SortDirection;
 	};
 
 	/**
@@ -141,4 +212,198 @@ export interface View {
 	 * The number of items per page
 	 */
 	perPage?: number;
+
+	/**
+	 * The hidden fields.
+	 */
+	hiddenFields: string[];
+}
+
+export interface ViewTable extends ViewBase {
+	type: 'table';
+
+	layout: {
+		/**
+		 * The field to use as the primary field.
+		 */
+		primaryField?: string;
+
+		/**
+		 * The field to use as the media field.
+		 */
+		mediaField?: string;
+	};
 }
+
+export interface ViewList extends ViewBase {
+	type: 'list';
+
+	layout: {
+		/**
+		 * The field to use as the primary field.
+		 */
+		primaryField?: string;
+
+		/**
+		 * The field to use as the media field.
+		 */
+		mediaField?: string;
+	};
+}
+
+export interface ViewGrid extends ViewBase {
+	type: 'grid';
+
+	layout: {
+		/**
+		 * The field to use as the primary field.
+		 */
+		primaryField?: string;
+
+		/**
+		 * The field to use as the media field.
+		 */
+		mediaField?: string;
+
+		/**
+		 * The fields to use as columns.
+		 */
+		columnFields?: string[];
+
+		/**
+		 * The fields to use as badge fields.
+		 */
+		badgeFields?: string[];
+	};
+}
+
+export type View = ViewList | ViewGrid | ViewTable;
+
+interface ActionBase< Item extends AnyItem > {
+	/**
+	 * The unique identifier of the action.
+	 */
+	id: string;
+
+	/**
+	 * The label of the action.
+	 * In case we want to adjust the label based on the selected items,
+	 * a function can be provided.
+	 */
+	label: string | ( ( items: Item[] ) => string );
+
+	/**
+	 * The icon of the action. (Either a string or an SVG element)
+	 * This should be IconType from the components package
+	 * but that import is breaking typescript build for the moment.
+	 */
+	icon?: any;
+
+	/**
+	 * Whether the action is disabled.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Whether the action is destructive.
+	 */
+	isDestructive?: boolean;
+
+	/**
+	 * Whether the action is a primary action.
+	 */
+	isPrimary?: boolean;
+
+	/**
+	 * Whether the item passed as an argument supports the current action.
+	 */
+	isEligible?: ( item: Item ) => boolean;
+
+	/**
+	 * Whether the action can be used as a bulk action.
+	 */
+	supportsBulk?: boolean;
+}
+
+export interface ActionModal< Item extends AnyItem >
+	extends ActionBase< Item > {
+	/**
+	 * The callback to execute when the action has finished.
+	 */
+	onActionPerformed: ( ( items: Item[] ) => void ) | undefined;
+
+	/**
+	 * The callback to execute when the action is triggered.
+	 */
+	onActionStart: ( ( items: Item[] ) => void ) | undefined;
+
+	/**
+	 * Modal to render when the action is triggered.
+	 */
+	RenderModal: ( {
+		items,
+		closeModal,
+		onActionStart,
+		onActionPerformed,
+	}: {
+		items: Item[];
+		closeModal?: () => void;
+		onActionStart?: ( items: Item[] ) => void;
+		onActionPerformed?: ( items: Item[] ) => void;
+	} ) => ReactElement;
+
+	/**
+	 * Whether to hide the modal header.
+	 */
+	hideModalHeader?: boolean;
+
+	/**
+	 * The header of the modal.
+	 */
+	modalHeader?: string;
+}
+
+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< Item extends AnyItem > =
+	| ActionModal< Item >
+	| ActionButton< Item >;
+
+export interface ViewBaseProps< Item extends AnyItem > {
+	actions: Action< Item >[];
+	data: Item[];
+	fields: NormalizedField< Item >[];
+	getItemId: ( item: Item ) => string;
+	isLoading?: boolean;
+	onChangeView( view: View ): void;
+	onSelectionChange: ( items: Item[] ) => void;
+	selection: string[];
+	setOpenedFilter: ( fieldId: string ) => void;
+	view: View;
+}
+
+export interface ViewTableProps< Item extends AnyItem >
+	extends ViewBaseProps< Item > {
+	view: ViewTable;
+}
+
+export interface ViewListProps< Item extends AnyItem >
+	extends ViewBaseProps< Item > {
+	view: ViewList;
+}
+
+export interface ViewGridProps< Item extends AnyItem >
+	extends ViewBaseProps< Item > {
+	view: ViewGrid;
+}
+
+export type ViewProps< Item extends AnyItem > =
+	| ViewTableProps< Item >
+	| ViewGridProps< Item >
+	| ViewListProps< Item >;

package/src/{utils.js → utils.ts}

@@ -8,8 +8,11 @@ import {
 	OPERATOR_IS_ANY,
 	OPERATOR_IS_NONE,
 } from './constants';
+import type { AnyItem, NormalizedField } from './types';
 
-export const sanitizeOperators = ( field ) => {
+export function sanitizeOperators< Item extends AnyItem >(
+	field: NormalizedField< Item >
+) {
 	let operators = field.filterBy?.operators;
 
 	// Assign default values.
@@ -17,17 +20,6 @@ export const sanitizeOperators = ( field ) => {
 		operators = [ OPERATOR_IS_ANY, OPERATOR_IS_NONE ];
 	}
 
-	// Transform legacy in, notIn operators to is, isNot.
-	// To be removed in the future.
-	if ( operators.includes( 'in' ) ) {
-		operators = operators.filter( ( operator ) => operator !== 'is' );
-		operators.push( 'is' );
-	}
-	if ( operators.includes( 'notIn' ) ) {
-		operators = operators.filter( ( operator ) => operator !== 'notIn' );
-		operators.push( 'isNot' );
-	}
-
 	// Make sure only valid operators are used.
 	operators = operators.filter( ( operator ) =>
 		ALL_OPERATORS.includes( operator )
@@ -45,4 +37,4 @@ export const sanitizeOperators = ( field ) => {
 	}
 
 	return operators;
-};
+}

package/src/{view-actions.js → view-actions.tsx}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ChangeEvent } from 'react';
+
 /**
  * WordPress dependencies
  */
@@ -13,8 +18,9 @@ import { settings } from '@wordpress/icons';
  * Internal dependencies
  */
 import { unlock } from './lock-unlock';
-import { SORTING_DIRECTIONS } from './constants';
+import { SORTING_DIRECTIONS, sortLabels } from './constants';
 import { VIEW_LAYOUTS } from './layouts';
+import type { AnyItem, NormalizedField, View } from './types';
 
 const {
 	DropdownMenuV2: DropdownMenu,
@@ -25,7 +31,41 @@ const {
 	DropdownMenuItemLabelV2: DropdownMenuItemLabel,
 } = unlock( componentsPrivateApis );
 
-function ViewTypeMenu( { view, onChangeView, supportedLayouts } ) {
+interface ViewTypeMenuProps {
+	view: View;
+	onChangeView: ( view: View ) => void;
+	supportedLayouts?: string[];
+}
+
+interface PageSizeMenuProps {
+	view: View;
+	onChangeView: ( view: View ) => void;
+}
+
+interface FieldsVisibilityMenuProps< Item extends AnyItem > {
+	view: View;
+	onChangeView: ( view: View ) => void;
+	fields: NormalizedField< Item >[];
+}
+
+interface SortMenuProps< Item extends AnyItem > {
+	fields: NormalizedField< Item >[];
+	view: View;
+	onChangeView: ( view: View ) => void;
+}
+
+interface ViewActionsProps< Item extends AnyItem > {
+	fields: NormalizedField< Item >[];
+	view: View;
+	onChangeView: ( view: View ) => void;
+	supportedLayouts?: string[];
+}
+
+function ViewTypeMenu( {
+	view,
+	onChangeView,
+	supportedLayouts,
+}: ViewTypeMenuProps ) {
 	let _availableViews = VIEW_LAYOUTS;
 	if ( supportedLayouts ) {
 		_availableViews = _availableViews.filter( ( _view ) =>
@@ -41,7 +81,7 @@ function ViewTypeMenu( { view, onChangeView, supportedLayouts } ) {
 			trigger={
 				<DropdownMenuItem
 					suffix={
-						<span aria-hidden="true">{ activeView.label }</span>
+						<span aria-hidden="true">{ activeView?.label }</span>
 					}
 				>
 					<DropdownMenuItemLabel>
@@ -58,11 +98,18 @@ function ViewTypeMenu( { view, onChangeView, supportedLayouts } ) {
 						name="view-actions-available-view"
 						checked={ availableView.type === view.type }
 						hideOnClick
-						onChange={ ( e ) => {
-							onChangeView( {
-								...view,
-								type: e.target.value,
-							} );
+						onChange={ ( e: ChangeEvent< HTMLInputElement > ) => {
+							switch ( e.target.value ) {
+								case 'list':
+								case 'grid':
+								case 'table':
+									return onChangeView( {
+										...view,
+										type: e.target.value,
+										layout: {},
+									} );
+							}
+							throw new Error( 'Invalid dataview' );
 						} }
 					>
 						<DropdownMenuItemLabel>
@@ -76,7 +123,7 @@ function ViewTypeMenu( { view, onChangeView, supportedLayouts } ) {
 }
 
 const PAGE_SIZE_VALUES = [ 10, 20, 50, 100 ];
-function PageSizeMenu( { view, onChangeView } ) {
+function PageSizeMenu( { view, onChangeView }: PageSizeMenuProps ) {
 	return (
 		<DropdownMenu
 			trigger={
@@ -114,7 +161,11 @@ function PageSizeMenu( { view, onChangeView } ) {
 	);
 }
 
-function FieldsVisibilityMenu( { view, onChangeView, fields } ) {
+function FieldsVisibilityMenu< Item extends AnyItem >( {
+	view,
+	onChangeView,
+	fields,
+}: FieldsVisibilityMenuProps< Item > ) {
 	const hidableFields = fields.filter(
 		( field ) =>
 			field.enableHiding !== false && field.id !== view.layout.mediaField
@@ -164,7 +215,11 @@ function FieldsVisibilityMenu( { view, onChangeView, fields } ) {
 	);
 }
 
-function SortMenu( { fields, view, onChangeView } ) {
+function SortMenu< Item extends AnyItem >( {
+	fields,
+	view,
+	onChangeView,
+}: SortMenuProps< Item > ) {
 	const sortableFields = fields.filter(
 		( field ) => field.enableSorting !== false
 	);
@@ -206,43 +261,41 @@ function SortMenu( { fields, view, onChangeView } ) {
 							minWidth: '220px',
 						} }
 					>
-						{ Object.entries( SORTING_DIRECTIONS ).map(
-							( [ direction, info ] ) => {
-								const isChecked =
-									currentSortedField !== undefined &&
-									sortedDirection === direction &&
-									field.id === currentSortedField.id;
+						{ SORTING_DIRECTIONS.map( ( direction ) => {
+							const isChecked =
+								currentSortedField !== undefined &&
+								sortedDirection === direction &&
+								field.id === currentSortedField.id;
 
-								const value = `${ field.id }-${ direction }`;
+							const value = `${ field.id }-${ direction }`;
 
-								return (
-									<DropdownMenuRadioItem
-										key={ value }
-										// All sorting radio items share the same name, so that
-										// selecting a sorting option automatically deselects the
-										// previously selected one, even if it is displayed in
-										// another submenu. The field and direction are passed via
-										// the `value` prop.
-										name="view-actions-sorting"
-										value={ value }
-										checked={ isChecked }
-										onChange={ () => {
-											onChangeView( {
-												...view,
-												sort: {
-													field: field.id,
-													direction,
-												},
-											} );
-										} }
-									>
-										<DropdownMenuItemLabel>
-											{ info.label }
-										</DropdownMenuItemLabel>
-									</DropdownMenuRadioItem>
-								);
-							}
-						) }
+							return (
+								<DropdownMenuRadioItem
+									key={ value }
+									// All sorting radio items share the same name, so that
+									// selecting a sorting option automatically deselects the
+									// previously selected one, even if it is displayed in
+									// another submenu. The field and direction are passed via
+									// the `value` prop.
+									name="view-actions-sorting"
+									value={ value }
+									checked={ isChecked }
+									onChange={ () => {
+										onChangeView( {
+											...view,
+											sort: {
+												field: field.id,
+												direction,
+											},
+										} );
+									} }
+								>
+									<DropdownMenuItemLabel>
+										{ sortLabels[ direction ] }
+									</DropdownMenuItemLabel>
+								</DropdownMenuRadioItem>
+							);
+						} ) }
 					</DropdownMenu>
 				);
 			} ) }
@@ -250,12 +303,12 @@ function SortMenu( { fields, view, onChangeView } ) {
 	);
 }
 
-const ViewActions = memo( function ViewActions( {
+function _ViewActions< Item extends AnyItem >( {
 	fields,
 	view,
 	onChangeView,
 	supportedLayouts,
-} ) {
+}: ViewActionsProps< Item > ) {
 	return (
 		<DropdownMenu
 			trigger={
@@ -286,6 +339,9 @@ const ViewActions = memo( function ViewActions( {
 			</DropdownMenuGroup>
 		</DropdownMenu>
 	);
-} );
+}
+
+// A type assertion is used here to keep the type argument.
+const ViewActions = memo( _ViewActions ) as typeof _ViewActions;
 
 export default ViewActions;