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

package/src/components/dataviews/README.md

@@ -1,107 +1,194 @@
 # DataView
 
-This file aims to document the main APIs related to the DataView component.
+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 is responsible for configuring how the dataset is visible to the user. For example:
+The view object configures how the dataset is visible to the user.
+
+Example:
 
 ```js
 {
 	type: 'list',
-	page: 1,
 	perPage: 5,
+	page: 1,
 	sort: {
 		field: 'date',
 		direction: 'desc',
 	},
+	search: '',
 	filters: {
-		search: '',
 		author: 2,
 		status: 'publish, draft'
 	},
-	visibleFilters: [ 'search', 'author', 'status' ],
+	visibleFilters: [ 'author', 'status' ],
 	hiddenFields: [ 'date', 'featured-image' ],
 	layout: {},
 }
 ```
 
-- `type`: one of `list` or `grid`.
-- `page`: the current page.
-- `perPage`: number of records per page.
-- `sort.field`: field used for sorting.
-- `sort.direction`: one of `asc` or `desc`.
-- `filters`: the filters applied to the dataset.
+- `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`: ...
 
-The view configuration is used to retrieve the corresponding entity that holds the dataset:
+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
-const {
-	records: pages,
-	isLoading: isLoadingPages,
-	totalItems,
-	totalPages
-} = useEntityRecords( 'postType', 'page', {
-	per_page: view.perPage,
-	page: view.page,
-	order: view.sort?.direction,
-	orderby: view.sort?.field
-	...view.filters
-} );
+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 dataset. For example:
+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} ) => {
+		render: ( { item } ) => {
 			return (
 				<a href="...">{ item.author }</a>
 			);
 		},
 		elements: [
-			{ value: 1, label: 'admin' }
-			{ value: 2, label: 'user' }
+			{ value: 1, label: 'Admin' }
+			{ value: 2, label: 'User' }
 		]
-		filters: [
-			{ id: 'author', type: 'enumeration' },
-			{ id: 'author_search', type: 'search' }
-		],
-	},
+		filters: [ 'enumeration' ],
+	}
 ]
 ```
 
 - `id`: identifier for the field. Unique.
-- `header`: the field name for the UI.
+- `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`: a set of valid values for the field.
-- `filters`: what filters are available. A filter is an object with `id` and `type` as properties:
-	- `id`: unique identifier for the filter. Matches the entity query param.
-	- `type`: the type of filter. One of `search` or `enumeration`.
-
+- `elements`: the set of valid values for the field's value.
+- `filters`: what filters are available for the user to use. See filters section.
 
-## DataViews
+## Filters
 
-The UI component responsible for rendering the dataset.
+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
-	data={ pages }
-	isLoading= { isLoadingPages }
 	fields={ fields }
-	view={ view }
-	onChangeView={ onChangeView }
-	actions={ [ trashPostAction ] }
-	paginationInfo={ { totalItems, totalPages } }
 />
 ```
+
+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

@@ -14,12 +14,15 @@ import ViewList from './view-list';
 import Pagination from './pagination';
 import ViewActions from './view-actions';
 import Filters from './filters';
+import Search from './search';
 import { ViewGrid } from './view-grid';
 
 export default function DataViews( {
 	view,
 	onChangeView,
 	fields,
+	search = true,
+	searchLabel = undefined,
 	actions,
 	data,
 	isLoading = false,
@@ -34,9 +37,16 @@ export default function DataViews( {
 	}, [ fields ] );
 	return (
 		<div className="dataviews-wrapper">
-			<VStack spacing={ 4 }>
+			<VStack spacing={ 4 } justify="flex-start">
 				<HStack>
 					<HStack justify="start">
+						{ search && (
+							<Search
+								label={ searchLabel }
+								view={ view }
+								onChangeView={ onChangeView }
+							/>
+						) }
 						<Filters
 							fields={ fields }
 							view={ view }

package/src/components/dataviews/filters.js

@@ -6,45 +6,63 @@ import { __ } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
-import TextFilter from './text-filter';
 import InFilter from './in-filter';
 
 export default function Filters( { fields, view, onChangeView } ) {
-	const filters = {};
+	const filterIndex = {};
 	fields.forEach( ( field ) => {
 		if ( ! field.filters ) {
 			return;
 		}
 
-		field.filters.forEach( ( f ) => {
-			filters[ f.id ] = { type: f.type };
+		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 = filters[ filterName ];
+			const filter = filterIndex[ filterName ];
 
 			if ( ! filter ) {
 				return null;
 			}
 
-			if ( filter.type === 'search' ) {
-				return (
-					<TextFilter
-						key={ filterName }
-						id={ filterName }
-						view={ view }
-						onChangeView={ onChangeView }
-					/>
-				);
-			}
 			if ( filter.type === 'enumeration' ) {
 				return (
 					<InFilter
 						key={ filterName }
-						id={ filterName }
-						fields={ fields }
+						filter={ filter }
 						view={ view }
 						onChangeView={ onChangeView }
 					/>

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

@@ -14,21 +14,19 @@ import { unlock } from '../../lock-unlock';
 
 const { cleanEmptyObject } = unlock( blockEditorPrivateApis );
 
-export default ( { id, fields, view, onChangeView } ) => {
-	const field = fields.find( ( f ) => f.id === id );
-
+export default ( { filter, view, onChangeView } ) => {
 	return (
 		<SelectControl
-			value={ view.filters[ id ] }
+			value={ view.filters[ filter.id ] }
 			prefix={
 				<InputControlPrefixWrapper
 					as="span"
 					className="dataviews__select-control-prefix"
 				>
-					{ field.header + ':' }
+					{ filter.name + ':' }
 				</InputControlPrefixWrapper>
 			}
-			options={ field?.elements || [] }
+			options={ filter.elements }
 			onChange={ ( value ) => {
 				if ( value === '' ) {
 					value = undefined;
@@ -38,7 +36,7 @@ export default ( { id, fields, view, onChangeView } ) => {
 					...currentView,
 					filters: cleanEmptyObject( {
 						...currentView.filters,
-						[ id ]: value,
+						[ filter.id ]: value,
 					} ),
 				} ) );
 			} }

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

@@ -6,45 +6,11 @@ import {
 	__experimentalHStack as HStack,
 	__experimentalText as Text,
 	__experimentalNumberControl as NumberControl,
-	__experimentalInputControlPrefixWrapper as InputControlPrefixWrapper,
-	SelectControl,
 } from '@wordpress/components';
 import { createInterpolateElement } from '@wordpress/element';
 import { sprintf, __, _x, _n } from '@wordpress/i18n';
+import { chevronRight, chevronLeft, previous, next } from '@wordpress/icons';
 
-const PAGE_SIZE_VALUES = [ 5, 20, 50 ];
-function PageSizeControl( { view, onChangeView } ) {
-	const label = __( 'Rows per page:' );
-	return (
-		<SelectControl
-			__nextHasNoMarginBottom
-			label={ label }
-			hideLabelFromVision
-			// TODO: This should probably use a label based on the wanted design
-			// and we could remove InputControlPrefixWrapper usage.
-			prefix={
-				<InputControlPrefixWrapper
-					as="span"
-					className="dataviews__select-control-prefix"
-				>
-					{ label }
-				</InputControlPrefixWrapper>
-			}
-			value={ view.perPage }
-			options={ PAGE_SIZE_VALUES.map( ( pageSize ) => ( {
-				value: pageSize,
-				label: pageSize,
-			} ) ) }
-			onChange={ ( value ) =>
-				onChangeView( { ...view, perPage: value, page: 1 } )
-			}
-		/>
-	);
-}
-
-// 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.
 function Pagination( {
 	view,
 	onChangeView,
@@ -71,29 +37,37 @@ function Pagination( {
 				}
 			</Text>
 			{ !! totalItems && (
-				<HStack expanded={ false } spacing={ 1 }>
-					<Button
-						variant="tertiary"
-						onClick={ () => onChangeView( { ...view, page: 1 } ) }
-						disabled={ view.page === 1 }
-						aria-label={ __( 'First page' ) }
-					>
-						«
-					</Button>
-					<Button
-						variant="tertiary"
-						onClick={ () =>
-							onChangeView( { ...view, page: view.page - 1 } )
-						}
-						disabled={ view.page === 1 }
-						aria-label={ __( 'Previous page' ) }
-					>
-						‹
-					</Button>
+				<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(
@@ -130,29 +104,34 @@ function Pagination( {
 							}
 						) }
 					</HStack>
-					<Button
-						variant="tertiary"
-						onClick={ () =>
-							onChangeView( { ...view, page: view.page + 1 } )
-						}
-						disabled={ view.page >= totalPages }
-						aria-label={ __( 'Next page' ) }
-					>
-						›
-					</Button>
-					<Button
-						variant="tertiary"
-						onClick={ () =>
-							onChangeView( { ...view, page: totalPages } )
-						}
-						disabled={ view.page >= totalPages }
-						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 view={ view } onChangeView={ onChangeView } />
 		</HStack>
 	);
 }

package/src/components/dataviews/{text-filter.js → search.js}

@@ -10,10 +10,13 @@ import { SearchControl } from '@wordpress/components';
  */
 import useDebouncedInput from '../../utils/use-debounced-input';
 
-export default function TextFilter( { id, view, onChangeView } ) {
+export default function Search( { label, view, onChangeView } ) {
 	const [ search, setSearch, debouncedSearch ] = useDebouncedInput(
-		view.filters[ id ]
+		view.search
 	);
+	useEffect( () => {
+		setSearch( view.search );
+	}, [ view ] );
 	const onChangeViewRef = useRef( onChangeView );
 	useEffect( () => {
 		onChangeViewRef.current = onChangeView;
@@ -22,13 +25,10 @@ export default function TextFilter( { id, view, onChangeView } ) {
 		onChangeViewRef.current( ( currentView ) => ( {
 			...currentView,
 			page: 1,
-			filters: {
-				...currentView.filters,
-				[ id ]: debouncedSearch,
-			},
+			search: debouncedSearch,
 		} ) );
 	}, [ debouncedSearch ] );
-	const searchLabel = __( 'Filter list' );
+	const searchLabel = label || __( 'Filter list' );
 	return (
 		<SearchControl
 			onChange={ setSearch }

package/src/components/dataviews/style.scss

@@ -1,6 +1,16 @@
 .dataviews-wrapper {
 	width: 100%;
+	height: 100%;
+	overflow: auto;
 	padding: $grid-unit-40;
+
+	> div {
+		min-height: 100%;
+	}
+}
+
+.dataviews-pagination {
+	margin-top: auto;
 }
 
 .dataviews-list-view {
@@ -30,11 +40,6 @@
 	}
 }
 
-.dataviews__select-control-prefix {
-	color: $gray-700;
-	text-wrap: nowrap;
-}
-
 .dataviews-view-grid__media {
 	width: 100%;
 	min-height: 200px;