@wordpress/edit-site 5.24.1 → 5.25.0

package/src/components/dataviews/README.md

@@ -1,191 +0,0 @@
-# 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 }
-	getItemId={ ( item ) => item.id }
-	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: [
-		{ field: 'author', operator: OPERATOR_IN, value: 2 },
-		{ field: 'status', operator: OPERATOR_IN, value: 'publish,draft' }
-	],
-	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. Each item describes:
-    -   `field`: which field this filter is bound to.
-    -   `operator`: which type of filter it is. Only `in` available at the moment.
-    -   `value`: the actual value selected by the user.
--   `hiddenFields`: the `id` of the fields that are hidden in the UI.
--   `layout`: config that is specific to a particular layout type.
-    -   `mediaField`: used by the `grid` layout. The `id` of the field to be used for rendering each card's media.
-    -   `primaryField`: used by the `grid` layout. The `id` of the field to be used for rendering each card's title.
-
-### View <=> data
-
-The view is a representation of the visible state of the dataset. Note, however, that it's the consumer's responsibility to work with the data provider to make sure the user options defined through the view's config (sort, pagination, filters, etc.) are respected.
-
-The following example shows how a view object is used to query the WordPress REST API via the entities abstraction. The same can be done with any other data provider.
-
-```js
-function MyCustomPageList() {
-	const [ view, setView ] = useState( {
-		type: 'list',
-		perPage: 5,
-		page: 1,
-		sort: {
-			field: 'date',
-			direction: 'desc',
-		},
-		search: '',
-		filters: [
-			{ field: 'author', operator: OPERATOR_IN, value: 2 },
-			{ field: 'status', operator: OPERATOR_IN, value: 'publish,draft' }
-		],
-		hiddenFields: [ 'date', 'featured-image' ],
-		layout: {},
-	} );
-
-	const queryArgs = useMemo( () => {
-		const filters = {};
-		view.filters.forEach( ( filter ) => {
-			if ( filter.field === 'status' && filter.operator === OPERATOR_IN ) {
-				filters.status = filter.value;
-			}
-			if ( filter.field === 'author' && filter.operator === OPERATOR_IN ) {
-				filters.author = filter.value;
-			}
-		} );
-		return {
-			per_page: view.perPage,
-			page: view.page,
-			_embed: 'author',
-			order: view.sort?.direction,
-			orderby: view.sort?.field,
-			search: view.search,
-			...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>
-			);
-		},
-		enableHiding: false
-	},
-	{
-		id: 'author',
-		header: __( 'Author' ),
-		getValue: ( { item } ) => item.author,
-		render: ( { item } ) => {
-			return (
-				<a href="...">{ item.author }</a>
-			);
-		},
-		type: ENUMERATION_TYPE,
-		elements: [
-			{ value: 1, label: 'Admin' }
-			{ value: 2, label: 'User' }
-		]
-		enableSorting: false
-	}
-]
-```
-
--   `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.
--   `type`: the type of the field. Used to generate the proper filters. Only `enumeration` available at the moment.
--   `enableSorting`: whether the data can be sorted by the given field. True by default.
--   `enableHiding`: whether the field can be hidden. True by default.
-
-## Actions
-
-Array of operations that can be performed upon each record. Each action is an object with the following properties:
-
--   `id`: string, required. Unique identifier of the action. For example, `move-to-trash`.
--   `label`: string, required. User facing description of the action. For example, `Move to Trash`.
--   `isPrimary`: boolean, optional. Whether the action should be listed inline (primary) or in hidden in the more actions menu (secondary).
--   `icon`: icon to show for primary actions. It's required for a primary action, otherwise the action would be considered secondary.
--   `isEligible`: function, optional. Whether the action can be performed for a given record. If not present, the action is considered to be eligible for all items. It takes the given record as input.
--   `isDestructive`: boolean, optional. Whether the action can delete data, in which case the UI would communicate it via red color.
--   `callback`: function, required unless `RenderModal` is provided. Callback function that takes the record as input and performs the required action.
--   `RenderModal`: ReactElement, optional. If an action requires that some UI be rendered in a modal, it can provide a component which takes as props the record as `item` and a `closeModal` function. When this prop is provided, the `callback` property is ignored.
--   `hideModalHeader`: boolean, optional. This property is used in combination with `RenderModal` and controls the visibility of the modal's header. If the action renders a modal and doesn't hide the header, the action's label is going to be used in the modal's header.

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

@@ -1,108 +0,0 @@
-/**
- * WordPress dependencies
- */
-import {
-	privateApis as componentsPrivateApis,
-	Button,
-	Icon,
-} from '@wordpress/components';
-import { chevronRightSmall, plus } from '@wordpress/icons';
-import { __ } from '@wordpress/i18n';
-
-/**
- * Internal dependencies
- */
-import { unlock } from '../../lock-unlock';
-import { ENUMERATION_TYPE, OPERATOR_IN } from './constants';
-
-const {
-	DropdownMenuV2: DropdownMenu,
-	DropdownSubMenuV2: DropdownSubMenu,
-	DropdownSubMenuTriggerV2: DropdownSubMenuTrigger,
-	DropdownMenuItemV2: DropdownMenuItem,
-} = unlock( componentsPrivateApis );
-
-export default function AddFilter( { fields, view, onChangeView } ) {
-	const filters = [];
-	fields.forEach( ( field ) => {
-		if ( ! field.type ) {
-			return;
-		}
-
-		switch ( field.type ) {
-			case ENUMERATION_TYPE:
-				filters.push( {
-					field: field.id,
-					name: field.header,
-					elements: field.elements || [],
-					isVisible: view.filters.some(
-						( f ) =>
-							f.field === field.id && f.operator === OPERATOR_IN
-					),
-				} );
-		}
-	} );
-
-	if ( filters.length === 0 ) {
-		return null;
-	}
-
-	return (
-		<DropdownMenu
-			label={ __( 'Add filter' ) }
-			trigger={
-				<Button
-					disabled={ filters.length === view.filters?.length }
-					__experimentalIsFocusable
-					variant="tertiary"
-					size="compact"
-				>
-					<Icon icon={ plus } style={ { flexShrink: 0 } } />
-					{ __( 'Add filter' ) }
-				</Button>
-			}
-		>
-			{ filters.map( ( filter ) => {
-				if ( filter.isVisible ) {
-					return null;
-				}
-
-				return (
-					<DropdownSubMenu
-						key={ filter.field }
-						trigger={
-							<DropdownSubMenuTrigger
-								suffix={ <Icon icon={ chevronRightSmall } /> }
-							>
-								{ filter.name }
-							</DropdownSubMenuTrigger>
-						}
-					>
-						{ filter.elements.map( ( element ) => (
-							<DropdownMenuItem
-								key={ element.value }
-								onSelect={ () => {
-									onChangeView( ( currentView ) => ( {
-										...currentView,
-										page: 1,
-										filters: [
-											...currentView.filters,
-											{
-												field: filter.field,
-												operator: OPERATOR_IN,
-												value: element.value,
-											},
-										],
-									} ) );
-								} }
-								role="menuitemcheckbox"
-							>
-								{ element.label }
-							</DropdownMenuItem>
-						) ) }
-					</DropdownSubMenu>
-				);
-			} ) }
-		</DropdownMenu>
-	);
-}

package/src/components/dataviews/constants.js

@@ -1,5 +0,0 @@
-// Field types.
-export const ENUMERATION_TYPE = 'enumeration';
-
-// Filter operators.
-export const OPERATOR_IN = 'in';

package/src/components/dataviews/dataviews.js

@@ -1,99 +0,0 @@
-/**
- * WordPress dependencies
- */
-import {
-	__experimentalVStack as VStack,
-	__experimentalHStack as HStack,
-} from '@wordpress/components';
-import { useMemo } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
-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';
-import { ViewSideBySide } from './view-side-by-side';
-
-// To do: convert to view type registry.
-export const viewTypeSupportsMap = {
-	list: {},
-	grid: {},
-	'side-by-side': {
-		preview: true,
-	},
-};
-
-const viewTypeMap = {
-	list: ViewList,
-	grid: ViewGrid,
-	'side-by-side': ViewSideBySide,
-};
-
-export default function DataViews( {
-	view,
-	onChangeView,
-	fields,
-	search = true,
-	searchLabel = undefined,
-	actions,
-	data,
-	getItemId,
-	isLoading = false,
-	paginationInfo,
-	supportedLayouts,
-} ) {
-	const ViewComponent = viewTypeMap[ view.type ];
-	const _fields = useMemo( () => {
-		return fields.map( ( field ) => ( {
-			...field,
-			render: field.render || field.getValue,
-		} ) );
-	}, [ fields ] );
-	return (
-		<div className="dataviews-wrapper">
-			<VStack spacing={ 4 } justify="flex-start">
-				<HStack alignment="flex-start">
-					<HStack justify="start" wrap>
-						{ search && (
-							<Search
-								label={ searchLabel }
-								view={ view }
-								onChangeView={ onChangeView }
-							/>
-						) }
-						<Filters
-							fields={ fields }
-							view={ view }
-							onChangeView={ onChangeView }
-						/>
-					</HStack>
-					<ViewActions
-						fields={ fields }
-						view={ view }
-						onChangeView={ onChangeView }
-						supportedLayouts={ supportedLayouts }
-					/>
-				</HStack>
-				<ViewComponent
-					fields={ _fields }
-					view={ view }
-					onChangeView={ onChangeView }
-					paginationInfo={ paginationInfo }
-					actions={ actions }
-					data={ data }
-					getItemId={ getItemId }
-					isLoading={ isLoading }
-				/>
-				<Pagination
-					view={ view }
-					onChangeView={ onChangeView }
-					paginationInfo={ paginationInfo }
-				/>
-			</VStack>
-		</div>
-	);
-}

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

@@ -1,79 +0,0 @@
-/**
- * WordPress dependencies
- */
-import {
-	Button,
-	privateApis as componentsPrivateApis,
-	Icon,
-} from '@wordpress/components';
-import { chevronDown } from '@wordpress/icons';
-import { __, sprintf } from '@wordpress/i18n';
-
-/**
- * Internal dependencies
- */
-import { OPERATOR_IN } from './constants';
-import { unlock } from '../../lock-unlock';
-
-const {
-	DropdownMenuV2: DropdownMenu,
-	DropdownMenuCheckboxItemV2: DropdownMenuCheckboxItem,
-} = unlock( componentsPrivateApis );
-
-export default function FilterSummary( { filter, view, onChangeView } ) {
-	const filterInView = view.filters.find( ( f ) => f.field === filter.field );
-	const activeElement = filter.elements.find(
-		( element ) => element.value === filterInView?.value
-	);
-
-	return (
-		<DropdownMenu
-			key={ filter.field }
-			trigger={
-				<Button variant="tertiary" size="compact" label={ filter.name }>
-					{ activeElement !== undefined
-						? sprintf(
-								/* translators: 1: Filter name. 2: filter value. e.g.: "Author is Admin". */
-								__( '%1$s is %2$s' ),
-								filter.name,
-								activeElement.label
-						  )
-						: filter.name }
-					<Icon icon={ chevronDown } style={ { flexShrink: 0 } } />
-				</Button>
-			}
-		>
-			{ filter.elements.map( ( element ) => {
-				return (
-					<DropdownMenuCheckboxItem
-						key={ element.value }
-						value={ element.value }
-						checked={ activeElement?.value === element.value }
-						onSelect={ () =>
-							onChangeView( ( currentView ) => ( {
-								...currentView,
-								page: 1,
-								filters: [
-									...view.filters.filter(
-										( f ) => f.field !== filter.field
-									),
-									{
-										field: filter.field,
-										operator: OPERATOR_IN,
-										value:
-											activeElement?.value ===
-											element.value
-												? undefined
-												: element.value,
-									},
-								],
-							} ) )
-						}
-					>
-						{ element.label }
-					</DropdownMenuCheckboxItem>
-				);
-			} ) }
-		</DropdownMenu>
-	);
-}

package/src/components/dataviews/filters.js

@@ -1,65 +0,0 @@
-/**
- * Internal dependencies
- */
-import FilterSummary from './filter-summary';
-import AddFilter from './add-filter';
-import ResetFilters from './reset-filters';
-import { ENUMERATION_TYPE, OPERATOR_IN } from './constants';
-
-export default function Filters( { fields, view, onChangeView } ) {
-	const filters = [];
-	fields.forEach( ( field ) => {
-		if ( ! field.type ) {
-			return;
-		}
-
-		switch ( field.type ) {
-			case ENUMERATION_TYPE:
-				filters.push( {
-					field: field.id,
-					name: field.header,
-					elements: field.elements || [],
-					isVisible: view.filters.some(
-						( f ) =>
-							f.field === field.id && f.operator === OPERATOR_IN
-					),
-				} );
-		}
-	} );
-
-	const filterComponents = filters.map( ( filter ) => {
-		if ( ! filter.isVisible ) {
-			return null;
-		}
-
-		return (
-			<FilterSummary
-				key={ filter.field + '.' + filter.operator }
-				filter={ filter }
-				view={ view }
-				onChangeView={ onChangeView }
-			/>
-		);
-	} );
-
-	filterComponents.push(
-		<AddFilter
-			key="add-filter"
-			fields={ fields }
-			view={ view }
-			onChangeView={ onChangeView }
-		/>
-	);
-
-	if ( filterComponents.length > 1 ) {
-		filterComponents.push(
-			<ResetFilters
-				key="reset-filters"
-				view={ view }
-				onChangeView={ onChangeView }
-			/>
-		);
-	}
-
-	return filterComponents;
-}

package/src/components/dataviews/index.js

@@ -1 +0,0 @@
-export { default as DataViews, viewTypeSupportsMap } from './dataviews';