@wordpress/dataviews 1.1.0 → 1.2.0

package/src/types.ts

@@ -1,23 +1,41 @@
 /**
  * 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.
+ */
+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 interface Field {
+export type AnyItem = Record< string, any >;
+
+/**
+ * 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.
@@ -101,7 +128,7 @@ export interface Filter {
 	value: any;
 }
 
-export interface View {
+interface ViewBase {
 	/**
 	 * The layout of the view.
 	 */
@@ -129,7 +156,7 @@ export interface View {
 		/**
 		 * The direction to sort by.
 		 */
-		direction: string;
+		direction: SortDirection;
 	};
 
 	/**
@@ -141,4 +168,147 @@ export interface View {
 	 * The number of items per page
 	 */
 	perPage?: number;
+
+	/**
+	 * The hidden fields.
+	 */
+	hiddenFields: 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 | ViewBase;
+
+interface ActionBase< Item extends AnyItem > {
+	/**
+	 * The unique identifier of the action.
+	 */
+	id: string;
+
+	/**
+	 * The label of the action.
+	 */
+	label: 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 >;

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import classnames from 'classnames';
+import clsx from 'clsx';
 
 /**
  * WordPress dependencies
@@ -21,10 +21,40 @@ import { __ } from '@wordpress/i18n';
  */
 import ItemActions from './item-actions';
 import SingleSelectionCheckbox from './single-selection-checkbox';
-
 import { useHasAPossibleBulkAction } from './bulk-actions';
+import type {
+	Action,
+	AnyItem,
+	NormalizedField,
+	ViewGrid as ViewGridType,
+} from './types';
+
+interface GridItemProps< Item extends AnyItem > {
+	selection: string[];
+	data: Item[];
+	onSelectionChange: ( items: Item[] ) => void;
+	getItemId: ( item: Item ) => string;
+	item: Item;
+	actions: Action< Item >[];
+	mediaField?: NormalizedField< Item >;
+	primaryField?: NormalizedField< Item >;
+	visibleFields: NormalizedField< Item >[];
+	badgeFields: NormalizedField< Item >[];
+	columnFields: string[];
+}
 
-function GridItem( {
+interface ViewGridProps< Item extends AnyItem > {
+	actions: Action< Item >[];
+	data: Item[];
+	fields: NormalizedField< Item >[];
+	getItemId: ( item: Item ) => string;
+	isLoading: boolean;
+	onSelectionChange: ( items: Item[] ) => void;
+	selection: string[];
+	view: ViewGridType;
+}
+
+function GridItem< Item extends AnyItem >( {
 	selection,
 	data,
 	onSelectionChange,
@@ -36,7 +66,7 @@ function GridItem( {
 	visibleFields,
 	badgeFields,
 	columnFields,
-} ) {
+}: GridItemProps< Item > ) {
 	const hasBulkAction = useHasAPossibleBulkAction( actions, item );
 	const id = getItemId( item );
 	const isSelected = selection.includes( id );
@@ -44,7 +74,7 @@ function GridItem( {
 		<VStack
 			spacing={ 0 }
 			key={ id }
-			className={ classnames( 'dataviews-view-grid__card', {
+			className={ clsx( 'dataviews-view-grid__card', {
 				'is-selected': hasBulkAction && isSelected,
 			} ) }
 			onClickCapture={ ( event ) => {
@@ -86,7 +116,6 @@ function GridItem( {
 				className="dataviews-view-grid__title-actions"
 			>
 				<SingleSelectionCheckbox
-					id={ id }
 					item={ item }
 					selection={ selection }
 					onSelectionChange={ onSelectionChange }
@@ -105,7 +134,7 @@ function GridItem( {
 					className="dataviews-view-grid__badge-fields"
 					spacing={ 2 }
 					wrap
-					align="top"
+					alignment="top"
 					justify="flex-start"
 				>
 					{ badgeFields.map( ( field ) => {
@@ -137,7 +166,7 @@ function GridItem( {
 						}
 						return (
 							<Flex
-								className={ classnames(
+								className={ clsx(
 									'dataviews-view-grid__field',
 									columnFields?.includes( field.id )
 										? 'is-column'
@@ -174,16 +203,16 @@ function GridItem( {
 	);
 }
 
-export default function ViewGrid( {
+export default function ViewGrid< Item extends AnyItem >( {
+	actions,
 	data,
 	fields,
-	view,
-	actions,
-	isLoading,
 	getItemId,
-	selection,
+	isLoading,
 	onSelectionChange,
-} ) {
+	selection,
+	view,
+}: ViewGridProps< Item > ) {
 	const mediaField = fields.find(
 		( field ) => field.id === view.layout.mediaField
 	);
@@ -191,7 +220,7 @@ export default function ViewGrid( {
 		( field ) => field.id === view.layout.primaryField
 	);
 	const { visibleFields, badgeFields } = fields.reduce(
-		( accumulator, field ) => {
+		( accumulator: Record< string, NormalizedField< Item >[] >, field ) => {
 			if (
 				view.hiddenFields.includes( field.id ) ||
 				[ view.layout.mediaField, view.layout.primaryField ].includes(
@@ -243,7 +272,7 @@ export default function ViewGrid( {
 			) }
 			{ ! hasData && (
 				<div
-					className={ classnames( {
+					className={ clsx( {
 						'dataviews-loading': isLoading,
 						'dataviews-no-results': ! isLoading,
 					} ) }