@wordpress/edit-site 5.20.1 → 5.21.1-next.f8d8eceb.0

package/src/components/dataviews/README.md

@@ -0,0 +1,194 @@
+# DataView
+
+This file documents the DataViews UI component, which provides an API to render datasets using different view types (table, grid, etc.).
+
+```js
+<DataViews
+	data={ pages }
+	isLoading= { isLoadingPages }
+	view={ view }
+	onChangeView={ onChangeView }
+	fields={ fields }
+	actions={ [ trashPostAction ] }
+	paginationInfo={ { totalItems, totalPages } }
+/>
+```
+
+## Data
+
+The dataset to work with, represented as a one-dimensional array. 
+
+Example:
+
+```js
+[
+	{ id: 1, title: "Title", ... },
+	{ ... }
+]
+```
+
+## View
+
+The view object configures how the dataset is visible to the user.
+
+Example:
+
+```js
+{
+	type: 'list',
+	perPage: 5,
+	page: 1,
+	sort: {
+		field: 'date',
+		direction: 'desc',
+	},
+	search: '',
+	filters: {
+		author: 2,
+		status: 'publish, draft'
+	},
+	visibleFilters: [ 'author', 'status' ],
+	hiddenFields: [ 'date', 'featured-image' ],
+	layout: {},
+}
+```
+
+- `type`: view type, one of `list` or `grid`.
+- `perPage`: number of records to show per page.
+- `page`: the page that is visible.
+- `sort.field`: field used for sorting the dataset.
+- `sort.direction`: the direction to use for sorting, one of `asc` or `desc`.
+- `search`: the text search applied to the dataset.
+- `filters`: the filters applied to the dataset. See filters section.
+- `visibleFilters`: the `id` of the filters that are visible in the UI.
+- `hiddenFields`: the `id` of the fields that are hidden in the UI.
+- `layout`: ...
+
+Note that it's the consumer's responsibility to provide the data and make sure the dataset corresponds to the view's config (sort, pagination, filters, etc.).
+
+Example:
+
+```js
+function MyCustomPageList() { 
+	const [ view, setView ] = useState( {
+		type: 'list',
+		page: 1,
+		"...": "..."
+	} );
+
+	const queryArgs = useMemo(
+		() => ( {
+			per_page: view.perPage,
+			page: view.page,
+			order: view.sort?.direction,
+			orderby: view.sort?.field
+			search: view.search,
+			...view.filters
+		} ),
+		[ view ]
+	);
+
+	const {
+		records
+	} = useEntityRecords( 'postType', 'page', queryArgs );
+
+	return (
+		<DataViews
+			data={ records }
+			view={ view }
+			onChangeView={ setView }
+			"..."
+		/>
+	);
+}
+```
+
+## Fields
+
+The fields describe the visible items for each record in the dataset.
+
+Example:
+
+```js
+[
+	{
+		id: 'date',
+		header: __( 'Date' ),
+		getValue: ( { item } ) => item.date,
+		render: ( { item } ) => {
+			return (
+				<time>{ getFormattedDate( item.date ) }</time>
+			);
+		}
+	},
+	{
+		id: 'author',
+		header: __( 'Author' ),
+		getValue: ( { item } ) => item.author,
+		render: ( { item } ) => {
+			return (
+				<a href="...">{ item.author }</a>
+			);
+		},
+		elements: [
+			{ value: 1, label: 'Admin' }
+			{ value: 2, label: 'User' }
+		]
+		filters: [ 'enumeration' ],
+	}
+]
+```
+
+- `id`: identifier for the field. Unique.
+- `header`: the field's name to be shown in the UI.
+- `getValue`: function that returns the value of the field.
+- `render`: function that renders the field.
+- `elements`: the set of valid values for the field's value.
+- `filters`: what filters are available for the user to use. See filters section.
+
+## Filters
+
+Filters describe the conditions a record should match to be listed as part of the dataset. Filters are provided per field.
+
+```js
+const field = [
+	{
+		id: 'author',
+		filters: [ 'enumeration' ],
+	}
+];
+
+<DataViews
+	fields={ fields }
+/>
+```
+
+A filter is an object that may contain the following properties:
+
+- `id`: unique identifier for the filter. Matches the entity query param. Field filters may omit it, in which case the field's `id` will be used.
+- `name`: nice looking name for the filter. Field filters may omit it, in which case the field's `header` will be used.
+- `type`: the type of filter. Only `enumeration` is supported at the moment.
+- `elements`: for filters of type `enumeration`, the list of options to show. A one-dimensional array of object with value/label keys, as in `[ { value: 1, label: "Value name" } ]`.
+	- `value`: what's serialized into the view's filters.
+	- `label`: nice-looking name for users.
+- `resetValue`: for filters of type `enumeration`, this is the value for the reset option. If none is provided, `''` will be used.
+- `resetLabel`: for filters of type `enumeration`, this is the label for the reset option. If none is provided, `All` will be used.
+
+As a convenience, field's filter can provide abbreviated versions for the filter. All of following examples result in the same filter:
+
+```js
+const field = [
+	{
+		id: 'author',
+		header: __( 'Author' ),
+		elements: authors,
+		filters: [
+			'enumeration',
+			{ type: 'enumeration' },
+			{ id: 'author', type: 'enumeration' },
+			{ id: 'author', type: 'enumeration', name: __( 'Author' ) },
+			{ id: 'author', type: 'enumeration', name: __( 'Author' ), elements: authors },
+		],
+	}
+];
+```

package/src/components/dataviews/context.js

@@ -0,0 +1,7 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext } from '@wordpress/element';
+
+const DataviewsContext = createContext( {} );
+export default DataviewsContext;

package/src/components/dataviews/dataviews.js

@@ -1,14 +1,3 @@
-/**
- * External dependencies
- */
-import {
-	getCoreRowModel,
-	getFilteredRowModel,
-	getSortedRowModel,
-	getPaginationRowModel,
-	useReactTable,
-} from '@tanstack/react-table';
-
 /**
  * WordPress dependencies
  */
@@ -16,43 +5,75 @@ import {
 	__experimentalVStack as VStack,
 	__experimentalHStack as HStack,
 } from '@wordpress/components';
+import { useMemo } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
-import ListView from './list-view';
-import { Pagination } from './pagination';
+import ViewList from './view-list';
+import Pagination from './pagination';
 import ViewActions from './view-actions';
-import TextFilter from './text-filter';
+import Filters from './filters';
+import Search from './search';
+import { ViewGrid } from './view-grid';
 
 export default function DataViews( {
-	data,
+	view,
+	onChangeView,
 	fields,
-	isLoading,
+	search = true,
+	searchLabel = undefined,
+	actions,
+	data,
+	isLoading = false,
 	paginationInfo,
-	options,
 } ) {
-	const dataView = useReactTable( {
-		data,
-		columns: fields,
-		...options,
-		getCoreRowModel: getCoreRowModel(),
-		getFilteredRowModel: getFilteredRowModel(),
-		getSortedRowModel: getSortedRowModel(),
-		getPaginationRowModel: getPaginationRowModel(),
-	} );
+	const ViewComponent = view.type === 'list' ? ViewList : ViewGrid;
+	const _fields = useMemo( () => {
+		return fields.map( ( field ) => ( {
+			...field,
+			render: field.render || field.getValue,
+		} ) );
+	}, [ fields ] );
 	return (
 		<div className="dataviews-wrapper">
-			<VStack spacing={ 4 }>
-				<HStack justify="space-between">
-					<TextFilter onChange={ dataView.setGlobalFilter } />
-					<ViewActions dataView={ dataView } />
+			<VStack spacing={ 4 } justify="flex-start">
+				<HStack>
+					<HStack justify="start">
+						{ search && (
+							<Search
+								label={ searchLabel }
+								view={ view }
+								onChangeView={ onChangeView }
+							/>
+						) }
+						<Filters
+							fields={ fields }
+							view={ view }
+							onChangeView={ onChangeView }
+						/>
+					</HStack>
+					<HStack justify="end">
+						<ViewActions
+							fields={ fields }
+							view={ view }
+							onChangeView={ onChangeView }
+						/>
+					</HStack>
 				</HStack>
-				{ /* This component will be selected based on viewConfigs. Now we only have the list view. */ }
-				<ListView dataView={ dataView } isLoading={ isLoading } />
+				<ViewComponent
+					fields={ _fields }
+					view={ view }
+					onChangeView={ onChangeView }
+					paginationInfo={ paginationInfo }
+					actions={ actions }
+					data={ data }
+					isLoading={ isLoading }
+				/>
 				<Pagination
-					dataView={ dataView }
-					totalItems={ paginationInfo?.totalItems }
+					view={ view }
+					onChangeView={ onChangeView }
+					paginationInfo={ paginationInfo }
 				/>
 			</VStack>
 		</div>

package/src/components/dataviews/filters.js

@@ -0,0 +1,75 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import InFilter from './in-filter';
+
+export default function Filters( { fields, view, onChangeView } ) {
+	const filterIndex = {};
+	fields.forEach( ( field ) => {
+		if ( ! field.filters ) {
+			return;
+		}
+
+		field.filters.forEach( ( filter ) => {
+			let id = field.id;
+			if ( 'string' === typeof filter ) {
+				filterIndex[ id ] = {
+					id,
+					name: field.header,
+					type: filter,
+				};
+			}
+
+			if ( 'object' === typeof filter ) {
+				id = filter.id || field.id;
+				filterIndex[ id ] = {
+					id,
+					name: filter.name || field.header,
+					type: filter.type,
+				};
+			}
+
+			if ( 'enumeration' === filterIndex[ id ]?.type ) {
+				const elements = [
+					{
+						value: filter.resetValue || '',
+						label: filter.resetLabel || __( 'All' ),
+					},
+					...( field.elements || [] ),
+				];
+				filterIndex[ id ] = {
+					...filterIndex[ id ],
+					elements,
+				};
+			}
+		} );
+	} );
+
+	return (
+		view.visibleFilters?.map( ( filterName ) => {
+			const filter = filterIndex[ filterName ];
+
+			if ( ! filter ) {
+				return null;
+			}
+
+			if ( filter.type === 'enumeration' ) {
+				return (
+					<InFilter
+						key={ filterName }
+						filter={ filter }
+						view={ view }
+						onChangeView={ onChangeView }
+					/>
+				);
+			}
+
+			return null;
+		} ) || __( 'No filters available' )
+	);
+}

package/src/components/dataviews/in-filter.js

@@ -0,0 +1,45 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	__experimentalInputControlPrefixWrapper as InputControlPrefixWrapper,
+	SelectControl,
+} from '@wordpress/components';
+import { privateApis as blockEditorPrivateApis } from '@wordpress/block-editor';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../../lock-unlock';
+
+const { cleanEmptyObject } = unlock( blockEditorPrivateApis );
+
+export default ( { filter, view, onChangeView } ) => {
+	return (
+		<SelectControl
+			value={ view.filters[ filter.id ] }
+			prefix={
+				<InputControlPrefixWrapper
+					as="span"
+					className="dataviews__select-control-prefix"
+				>
+					{ filter.name + ':' }
+				</InputControlPrefixWrapper>
+			}
+			options={ filter.elements }
+			onChange={ ( value ) => {
+				if ( value === '' ) {
+					value = undefined;
+				}
+
+				onChangeView( ( currentView ) => ( {
+					...currentView,
+					filters: cleanEmptyObject( {
+						...currentView.filters,
+						[ filter.id ]: value,
+					} ),
+				} ) );
+			} }
+		/>
+	);
+};

package/src/components/dataviews/index.js

@@ -1,2 +1 @@
 export { default as DataViews } from './dataviews';
-export { PAGE_SIZE_VALUES } from './view-actions';

package/src/components/dataviews/item-actions.js

@@ -0,0 +1,69 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	DropdownMenu,
+	MenuGroup,
+	MenuItem,
+	Button,
+	__experimentalHStack as HStack,
+} from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+import { useMemo } from '@wordpress/element';
+import { moreVertical } from '@wordpress/icons';
+
+export default function ItemActions( { item, actions } ) {
+	const { primaryActions, secondaryActions } = useMemo( () => {
+		return actions.reduce(
+			( accumulator, action ) => {
+				// If an action is eligible for all items, doesn't need
+				// to provide the `isEligible` function.
+				if ( action.isEligible && ! action.isEligible( item ) ) {
+					return accumulator;
+				}
+				if ( action.isPrimary && !! action.icon ) {
+					accumulator.primaryActions.push( action );
+				} else {
+					accumulator.secondaryActions.push( action );
+				}
+				return accumulator;
+			},
+			{ primaryActions: [], secondaryActions: [] }
+		);
+	}, [ actions, item ] );
+	if ( ! primaryActions.length && ! secondaryActions.length ) {
+		return null;
+	}
+	return (
+		<HStack justify="flex-end">
+			{ !! primaryActions.length &&
+				primaryActions.map( ( action ) => (
+					<Button
+						label={ action.label }
+						key={ action.id }
+						icon={ action.icon }
+						onClick={ () => action.perform( item ) }
+						isDestructive={ action.isDestructive }
+						size="compact"
+					/>
+				) ) }
+			{ !! secondaryActions.length && (
+				<DropdownMenu icon={ moreVertical } label={ __( 'Actions' ) }>
+					{ () => (
+						<MenuGroup>
+							{ secondaryActions.map( ( action ) => (
+								<MenuItem
+									key={ action.id }
+									onClick={ () => action.perform( item ) }
+									isDestructive={ action.isDestructive }
+								>
+									{ action.label }
+								</MenuItem>
+							) ) }
+						</MenuGroup>
+					) }
+				</DropdownMenu>
+			) }
+		</HStack>
+	);
+}

package/src/components/dataviews/pagination.js

@@ -9,23 +9,16 @@ import {
 } from '@wordpress/components';
 import { createInterpolateElement } from '@wordpress/element';
 import { sprintf, __, _x, _n } from '@wordpress/i18n';
+import { chevronRight, chevronLeft, previous, next } from '@wordpress/icons';
 
-/**
- * Internal dependencies
- */
-import { PageSizeControl } from './view-actions';
-
-// For now this is copied from the patterns list Pagination component, because
-// the datatable pagination starts from index zero(`0`). Eventually all lists will be
-// using this one.
-export function Pagination( {
-	dataView,
-	// If passed, use it, as it's for controlled pagination.
-	totalItems = 0,
+function Pagination( {
+	view,
+	onChangeView,
+	paginationInfo: { totalItems = 0, totalPages },
 } ) {
-	const currentPage = dataView.getState().pagination.pageIndex + 1;
-	const numPages = dataView.getPageCount();
-	const _totalItems = totalItems || dataView.getCoreRowModel().rows.length;
+	if ( ! totalItems || ! totalPages ) {
+		return null;
+	}
 	return (
 		<HStack
 			expanded={ false }
@@ -38,53 +31,72 @@ export function Pagination( {
 					// translators: %s: Total number of entries.
 					sprintf(
 						// translators: %s: Total number of entries.
-						_n( '%s item', '%s items', _totalItems ),
-						_totalItems
+						_n( '%s item', '%s items', totalItems ),
+						totalItems
 					)
 				}
 			</Text>
-			{ !! _totalItems && (
-				<HStack expanded={ false } spacing={ 1 }>
-					<Button
-						variant="tertiary"
-						onClick={ () => dataView.setPageIndex( 0 ) }
-						disabled={ ! dataView.getCanPreviousPage() }
-						aria-label={ __( 'First page' ) }
-					>
-						«
-					</Button>
-					<Button
-						variant="tertiary"
-						onClick={ () => dataView.previousPage() }
-						disabled={ ! dataView.getCanPreviousPage() }
-						aria-label={ __( 'Previous page' ) }
-					>
-						‹
-					</Button>
+			{ !! totalItems && (
+				<HStack expanded={ false } spacing={ 3 }>
 					<HStack
 						justify="flex-start"
 						expanded={ false }
 						spacing={ 1 }
+					>
+						<Button
+							onClick={ () =>
+								onChangeView( { ...view, page: 1 } )
+							}
+							disabled={ view.page === 1 }
+							label={ __( 'First page' ) }
+							icon={ previous }
+							showTooltip
+							size="compact"
+						/>
+						<Button
+							onClick={ () =>
+								onChangeView( { ...view, page: view.page - 1 } )
+							}
+							disabled={ view.page === 1 }
+							label={ __( 'Previous page' ) }
+							icon={ chevronLeft }
+							showTooltip
+							size="compact"
+						/>
+					</HStack>
+					<HStack
+						justify="flex-start"
+						expanded={ false }
+						spacing={ 2 }
 					>
 						{ createInterpolateElement(
 							sprintf(
 								// translators: %1$s: Current page number, %2$s: Total number of pages.
 								_x( '<CurrenPageControl /> of %2$s', 'paging' ),
-								currentPage,
-								numPages
+								view.page,
+								totalPages
 							),
 							{
 								CurrenPageControl: (
 									<NumberControl
 										aria-label={ __( 'Current page' ) }
 										min={ 1 }
-										max={ numPages }
+										max={ totalPages }
 										onChange={ ( value ) => {
-											if ( value > numPages ) return;
-											dataView.setPageIndex( value - 1 );
+											if (
+												! value ||
+												value < 1 ||
+												value > totalPages
+											) {
+												return;
+											}
+											onChangeView( {
+												...view,
+												page: value,
+											} );
 										} }
 										step="1"
-										value={ currentPage }
+										value={ view.page }
 										isDragEnabled={ false }
 										spinControls="none"
 									/>
@@ -92,27 +104,36 @@ export function Pagination( {
 							}
 						) }
 					</HStack>
-					<Button
-						variant="tertiary"
-						onClick={ () => dataView.nextPage() }
-						disabled={ ! dataView.getCanNextPage() }
-						aria-label={ __( 'Next page' ) }
-					>
-						›
-					</Button>
-					<Button
-						variant="tertiary"
-						onClick={ () =>
-							dataView.setPageIndex( dataView.getPageCount() - 1 )
-						}
-						disabled={ ! dataView.getCanNextPage() }
-						aria-label={ __( 'Last page' ) }
+					<HStack
+						justify="flex-start"
+						expanded={ false }
+						spacing={ 1 }
 					>
-						»
-					</Button>
+						<Button
+							onClick={ () =>
+								onChangeView( { ...view, page: view.page + 1 } )
+							}
+							disabled={ view.page >= totalPages }
+							label={ __( 'Next page' ) }
+							icon={ chevronRight }
+							showTooltip
+							size="compact"
+						/>
+						<Button
+							onClick={ () =>
+								onChangeView( { ...view, page: totalPages } )
+							}
+							disabled={ view.page >= totalPages }
+							label={ __( 'Last page' ) }
+							icon={ next }
+							showTooltip
+							size="compact"
+						/>
+					</HStack>
 				</HStack>
 			) }
-			<PageSizeControl dataView={ dataView } />
 		</HStack>
 	);
 }
+
+export default Pagination;