@wordpress/dataviews 5.0.0 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/dataviews",
-	"version": "5.0.0",
+	"version": "6.0.0",
 	"description": "DataViews is a component that provides an API to render datasets using different types of layouts (table, grid, list, etc.).",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -46,18 +46,19 @@
 	"dependencies": {
 		"@ariakit/react": "^0.4.15",
 		"@babel/runtime": "7.25.7",
-		"@wordpress/base-styles": "^6.3.0",
-		"@wordpress/components": "^30.0.0",
-		"@wordpress/compose": "^7.27.0",
-		"@wordpress/data": "^10.27.0",
-		"@wordpress/date": "^5.27.0",
-		"@wordpress/element": "^6.27.0",
-		"@wordpress/i18n": "^6.0.0",
-		"@wordpress/icons": "^10.27.0",
-		"@wordpress/primitives": "^4.27.0",
-		"@wordpress/private-apis": "^1.27.0",
-		"@wordpress/url": "^4.27.0",
-		"@wordpress/warning": "^3.27.0",
+		"@wordpress/base-styles": "^6.4.0",
+		"@wordpress/components": "^30.1.0",
+		"@wordpress/compose": "^7.28.0",
+		"@wordpress/data": "^10.28.0",
+		"@wordpress/date": "^5.28.0",
+		"@wordpress/element": "^6.28.0",
+		"@wordpress/i18n": "^6.1.0",
+		"@wordpress/icons": "^10.28.0",
+		"@wordpress/keycodes": "^4.28.0",
+		"@wordpress/primitives": "^4.28.0",
+		"@wordpress/private-apis": "^1.28.0",
+		"@wordpress/url": "^4.28.0",
+		"@wordpress/warning": "^3.28.0",
 		"clsx": "^2.1.1",
 		"date-fns": "^4.1.0",
 		"fast-deep-equal": "^3.1.3",
@@ -73,5 +74,5 @@
 	"scripts": {
 		"build:wp": "node build"
 	},
-	"gitHead": "abe06a6f2aef8d03c30ea9d5b3e133f041e523b1"
+	"gitHead": "28cc2098f5ee28f89096b638533796538f495f72"
 }

package/src/components/dataform/stories/index.story.tsx

@@ -1,13 +1,22 @@
 /**
  * WordPress dependencies
  */
-import { useMemo, useState } from '@wordpress/element';
+import { useCallback, useMemo, useState } from '@wordpress/element';
+import {
+	Button,
+	__experimentalVStack as VStack,
+	privateApis,
+} from '@wordpress/components';
 
 /**
  * Internal dependencies
  */
 import DataForm from '../index';
-import type { Field, Form } from '../../../types';
+import { isItemValid } from '../../../validation';
+import type { Field, Form, DataFormControlProps } from '../../../types';
+import { unlock } from '../../../lock-unlock';
+
+const { ValidatedTextControl } = unlock( privateApis );
 
 type SamplePost = {
 	title: string;
@@ -62,6 +71,7 @@ const fields = [
 		label: 'Date as options',
 		type: 'datetime' as const,
 		elements: [
+			{ value: '', label: 'Select a date' },
 			{ value: '1970-02-23T12:00:00', label: "Jane's birth date" },
 			{ value: '1950-02-23T12:00:00', label: "John's birth date" },
 		],
@@ -259,3 +269,220 @@ export const CombinedFields = {
 		type: 'panel',
 	},
 };
+
+function CustomEditControl< Item >( {
+	data,
+	field,
+	onChange,
+	hideLabelFromVision,
+}: DataFormControlProps< Item > ) {
+	const { id, label, placeholder, description } = field;
+	const value = field.getValue( { item: data } );
+
+	const onChangeControl = useCallback(
+		( newValue: string ) =>
+			onChange( {
+				[ id ]: newValue,
+			} ),
+		[ id, onChange ]
+	);
+
+	return (
+		<ValidatedTextControl
+			required={ !! field.isValid?.required }
+			label={ label }
+			placeholder={ placeholder }
+			value={ value ?? '' }
+			help={ description }
+			onChange={ onChangeControl }
+			__next40pxDefaultSize
+			__nextHasNoMarginBottom
+			hideLabelFromVision={ hideLabelFromVision }
+		/>
+	);
+}
+
+const DataFormValidationComponent = ( { required }: { required: boolean } ) => {
+	type ValidatedItem = {
+		text: string;
+		email: string;
+		integer: number;
+		boolean: boolean;
+		customEdit: string;
+		customValidation: string;
+	};
+
+	const [ post, setPost ] = useState< ValidatedItem >( {
+		text: 'Hello, World!',
+		email: 'hi@example.com',
+		integer: 2,
+		boolean: true,
+		customEdit: 'custom control',
+		customValidation: 'potato',
+	} );
+
+	const _fields: Field< ValidatedItem >[] = [
+		{
+			id: 'text',
+			type: 'text' as const,
+			label: 'Text',
+			isValid: {
+				required,
+			},
+		},
+		{
+			id: 'email',
+			type: 'email' as const,
+			label: 'e-mail',
+			isValid: {
+				required,
+			},
+		},
+		{
+			id: 'integer',
+			type: 'integer' as const,
+			label: 'Integer',
+			isValid: {
+				required,
+			},
+		},
+		{
+			id: 'boolean',
+			type: 'boolean' as const,
+			label: 'Boolean',
+			isValid: {
+				required,
+			},
+		},
+		{
+			id: 'customEdit',
+			label: 'Custom Control',
+			Edit: CustomEditControl,
+			isValid: {
+				required,
+			},
+		},
+		{
+			id: 'customValidation',
+			type: 'text',
+			label: 'Custom validation',
+			isValid: {
+				required,
+				custom: ( value: ValidatedItem ) => {
+					if (
+						! [ 'tomato', 'potato' ].includes(
+							value.customValidation
+						)
+					) {
+						return 'Value must be one of "tomato", "potato"';
+					}
+
+					return null;
+				},
+			},
+		},
+	];
+
+	const form = {
+		fields: [
+			'text',
+			'email',
+			'integer',
+			'boolean',
+			'customEdit',
+			'customValidation',
+		],
+	};
+
+	const canSave = isItemValid( post, _fields, form );
+
+	return (
+		<form>
+			<VStack alignment="left">
+				<DataForm< ValidatedItem >
+					data={ post }
+					fields={ _fields }
+					form={ form }
+					onChange={ ( edits ) =>
+						setPost( ( prev ) => ( {
+							...prev,
+							...edits,
+						} ) )
+					}
+				/>
+				<Button
+					__next40pxDefaultSize
+					accessibleWhenDisabled
+					disabled={ ! canSave }
+					variant="primary"
+				>
+					Submit
+				</Button>
+			</VStack>
+		</form>
+	);
+};
+
+export const Validation = {
+	title: 'DataForm/Validation',
+	render: DataFormValidationComponent,
+	argTypes: {
+		required: {
+			control: { type: 'boolean' },
+			description: 'Whether or not the fields are required.',
+		},
+	},
+	args: {
+		required: true,
+	},
+};
+
+const DataFormVisibilityComponent = () => {
+	type Post = {
+		name: string;
+		email: string;
+		isActive: boolean;
+	};
+	const [ data, setData ] = useState( {
+		name: '',
+		email: '',
+		isActive: true,
+	} );
+
+	const _fields = [
+		{ id: 'isActive', label: 'Is module active?', type: 'boolean' },
+		{
+			id: 'name',
+			label: 'Name',
+			type: 'text',
+			isVisible: ( post ) => post.isActive === true,
+		},
+		{
+			id: 'email',
+			label: 'Email',
+			type: 'email',
+			isVisible: ( post ) => post.isActive === true,
+		},
+	] satisfies Field< Post >[];
+	const form = {
+		fields: [ 'isActive', 'name', 'email' ],
+	};
+	return (
+		<DataForm< Post >
+			data={ data }
+			fields={ _fields }
+			form={ form }
+			onChange={ ( edits ) =>
+				setData( ( prev ) => ( {
+					...prev,
+					...edits,
+				} ) )
+			}
+		/>
+	);
+};
+
+export const Visibility = {
+	title: 'DataForm/Visibility',
+	render: DataFormVisibilityComponent,
+};

package/src/components/dataviews/index.tsx

@@ -7,8 +7,14 @@ import type { ReactNode, ComponentProps, ReactElement } from 'react';
  * WordPress dependencies
  */
 import { __experimentalHStack as HStack } from '@wordpress/components';
-import { useContext, useMemo, useRef, useState } from '@wordpress/element';
-import { useMergeRefs, useResizeObserver } from '@wordpress/compose';
+import {
+	useContext,
+	useMemo,
+	useRef,
+	useState,
+	useEffect,
+} from '@wordpress/element';
+import { useResizeObserver } from '@wordpress/compose';
 
 /**
  * Internal dependencies
@@ -59,7 +65,8 @@ type DataViewsProps< Item > = {
 	header?: ReactNode;
 	getItemLevel?: ( item: Item ) => number;
 	children?: ReactNode;
-	perPageSizes?: [ number, number, number, number ];
+	perPageSizes?: number[];
+	empty?: ReactNode;
 } & ( Item extends ItemWithId
 	? { getItemId?: ( item: Item ) => string }
 	: { getItemId: ( item: Item ) => string } );
@@ -133,7 +140,8 @@ function DataViews< Item >( {
 	isItemClickable = defaultIsItemClickable,
 	header,
 	children,
-	perPageSizes,
+	perPageSizes = [ 10, 20, 50, 100 ],
+	empty,
 }: DataViewsProps< Item > ) {
 	const containerRef = useRef< HTMLDivElement | null >( null );
 	const [ containerWidth, setContainerWidth ] = useState( 0 );
@@ -168,10 +176,23 @@ function DataViews< Item >( {
 	}, [ selection, data, getItemId ] );
 
 	const filters = useFilters( _fields, view );
-	const [ isShowingFilter, setIsShowingFilter ] = useState< boolean >( () =>
-		( filters || [] ).some( ( filter ) => filter.isPrimary )
+	const hasPrimaryOrLockedFilters = useMemo(
+		() =>
+			( filters || [] ).some(
+				( filter ) => filter.isPrimary || filter.isLocked
+			),
+		[ filters ]
+	);
+	const [ isShowingFilter, setIsShowingFilter ] = useState< boolean >(
+		hasPrimaryOrLockedFilters
 	);
 
+	useEffect( () => {
+		if ( hasPrimaryOrLockedFilters && ! isShowingFilter ) {
+			setIsShowingFilter( true );
+		}
+	}, [ hasPrimaryOrLockedFilters, isShowingFilter ] );
+
 	return (
 		<DataViewsContext.Provider
 			value={ {
@@ -193,17 +214,16 @@ function DataViews< Item >( {
 				renderItemLink,
 				containerWidth,
 				containerRef,
+				resizeObserverRef,
 				defaultLayouts,
 				filters,
 				isShowingFilter,
 				setIsShowingFilter,
 				perPageSizes,
+				empty,
 			} }
 		>
-			<div
-				className="dataviews-wrapper"
-				ref={ useMergeRefs( [ containerRef, resizeObserverRef ] ) }
-			>
+			<div className="dataviews-wrapper" ref={ containerRef }>
 				{ children ?? (
 					<DefaultUI
 						header={ header }

package/src/components/dataviews/stories/fixtures.tsx

@@ -41,7 +41,8 @@ export const data: SpaceObject[] = [
 	{
 		id: 1,
 		title: 'Moon',
-		description: "Earth's satellite",
+		description:
+			'The Moon is Earth’s only natural satellite, orbiting at an average distance of 384,400 kilometers with a synchronous rotation that leads to fixed lunar phases as seen from Earth. Its cratered surface and subtle glow define night skies, inspiring exploration missions and influencing tides and biological rhythms worldwide.',
 		image: 'https://live.staticflickr.com/7398/9458193857_e1256123e3_z.jpg',
 		type: 'Satellite',
 		isPlanet: false,
@@ -759,5 +760,6 @@ export const fields: Field< SpaceObject >[] = [
 			{ value: 'Gas giant', label: 'Gas giant' },
 		],
 		type: 'array',
+		enableGlobalSearch: true,
 	},
 ];

package/src/components/dataviews/stories/index.story.tsx

@@ -20,6 +20,7 @@ import {
 	__experimentalText as Text,
 	__experimentalHStack as HStack,
 	__experimentalVStack as VStack,
+	Button,
 } from '@wordpress/components';
 import { __, _n } from '@wordpress/i18n';
 
@@ -53,7 +54,7 @@ const defaultLayouts = {
 	[ LAYOUT_LIST ]: {},
 };
 
-export const Default = () => {
+export const Default = ( { perPageSizes = [ 10, 25, 50, 100 ] } ) => {
 	const [ view, setView ] = useState< View >( {
 		...DEFAULT_VIEW,
 		fields: [ 'categories' ],
@@ -86,10 +87,22 @@ export const Default = () => {
 			) }
 			isItemClickable={ () => true }
 			defaultLayouts={ defaultLayouts }
+			perPageSizes={ perPageSizes }
 		/>
 	);
 };
 
+Default.args = {
+	perPageSizes: [ 10, 25, 50, 100 ],
+};
+
+Default.argTypes = {
+	perPageSizes: {
+		control: 'object',
+		description: 'Array of available page sizes',
+	},
+};
+
 export const Empty = () => {
 	const [ view, setView ] = useState< View >( {
 		...DEFAULT_VIEW,
@@ -110,6 +123,27 @@ export const Empty = () => {
 	);
 };
 
+export const CustomEmpty = () => {
+	const [ view, setView ] = useState< View >( {
+		...DEFAULT_VIEW,
+		fields: [ 'title', 'description', 'categories' ],
+	} );
+
+	return (
+		<DataViews
+			getItemId={ ( item ) => item.id.toString() }
+			paginationInfo={ { totalItems: 0, totalPages: 0 } }
+			data={ [] }
+			view={ view }
+			fields={ fields }
+			onChangeView={ setView }
+			actions={ actions }
+			defaultLayouts={ defaultLayouts }
+			empty={ view.search ? 'No sites found' : 'No sites' }
+		/>
+	);
+};
+
 export const FieldsNoSortableNoHidable = () => {
 	const [ view, setView ] = useState< View >( {
 		...DEFAULT_VIEW,
@@ -261,6 +295,19 @@ export const FreeComposition = () => {
 					table: {},
 					grid: {},
 				} }
+				empty={
+					<VStack
+						justify="space-around"
+						alignment="center"
+						className="free-composition-dataviews-empty"
+					>
+						<Text size={ 18 } as="p">
+							No planets
+						</Text>
+						<Text variant="muted">{ `Try a different search because “${ view.search }” returned no results.` }</Text>
+						<Button variant="secondary">Create new planet</Button>
+					</VStack>
+				}
 			>
 				<PlanetOverview planets={ planets } />
 			</DataViews>
@@ -300,34 +347,7 @@ export const WithCard = () => {
 	);
 };
 
-export const CustomPerPageSizes = () => {
-	const [ view, setView ] = useState< View >( {
-		...DEFAULT_VIEW,
-		fields: [ 'categories' ],
-		titleField: 'title',
-		descriptionField: 'description',
-		mediaField: 'image',
-		perPage: 3,
-	} );
-	const { data: shownData, paginationInfo } = useMemo( () => {
-		return filterSortAndPaginate( data, view, fields );
-	}, [ view ] );
-	return (
-		<DataViews
-			getItemId={ ( item ) => item.id.toString() }
-			paginationInfo={ paginationInfo }
-			data={ shownData }
-			view={ view }
-			fields={ fields }
-			onChangeView={ setView }
-			actions={ actions.filter( ( action ) => ! action.supportsBulk ) }
-			defaultLayouts={ defaultLayouts }
-			perPageSizes={ [ 3, 6, 12, 24 ] }
-		/>
-	);
-};
-
-export const GroupedGridLayout = () => {
+export const GroupByLayout = () => {
 	const [ view, setView ] = useState< View >( {
 		type: LAYOUT_GRID,
 		search: '',

package/src/components/dataviews/stories/style.css

@@ -23,3 +23,9 @@
 .free-composition-dataviews-layout thead {
 	inset-block-start: 67px;
 }
+
+.free-composition-dataviews-empty  {
+	border: 1px solid #000;
+	border-radius: 8px;
+	padding: 24px;
+}

package/src/components/dataviews-context/index.ts

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ComponentProps, ReactElement } from 'react';
+import type { ComponentProps, ReactElement, ReactNode } from 'react';
 
 /**
  * WordPress dependencies
@@ -47,11 +47,15 @@ type DataViewsContextType< Item > = {
 	isItemClickable: ( item: Item ) => boolean;
 	containerWidth: number;
 	containerRef: React.MutableRefObject< HTMLDivElement | null >;
+	resizeObserverRef:
+		| ( ( element?: HTMLDivElement | null ) => void )
+		| React.RefObject< HTMLDivElement >;
 	defaultLayouts: SupportedLayouts;
 	filters: NormalizedFilter[];
 	isShowingFilter: boolean;
 	setIsShowingFilter: ( value: boolean ) => void;
-	perPageSizes?: [ number, number, number, number ];
+	perPageSizes: number[];
+	empty?: ReactNode;
 };
 
 const DataViewsContext = createContext< DataViewsContextType< any > >( {
@@ -72,10 +76,12 @@ const DataViewsContext = createContext< DataViewsContextType< any > >( {
 	renderItemLink: undefined,
 	containerWidth: 0,
 	containerRef: createRef(),
+	resizeObserverRef: () => {},
 	defaultLayouts: { list: {}, grid: {}, table: {} },
 	filters: [],
 	isShowingFilter: false,
 	setIsShowingFilter: () => {},
+	perPageSizes: [],
 } );
 
 export default DataViewsContext;

package/src/components/dataviews-filters/filter.tsx

@@ -309,9 +309,9 @@ const FilterText = ( {
 
 		return createInterpolateElement(
 			sprintf(
-				/* translators: 1: Filter name. 2: Min value. 3: Max value. e.g.: "Item count between (inc): 10-180". */
+				/* translators: 1: Filter name. 2: Min value. 3: Max value. e.g.: "Item count between (inc): 10 and 180". */
 				__(
-					'<Name>%1$s between (inc): </Name><Value>%2$s-%3$s</Value>'
+					'<Name>%1$s between (inc): </Name><Value>%2$s and %3$s</Value>'
 				),
 				filter.name,
 				label[ 0 ],
@@ -497,8 +497,9 @@ export default function Filter( {
 	}
 
 	const isPrimary = filter.isPrimary;
-	const hasValues = filterInView?.value !== undefined;
-	const canResetOrRemove = ! isPrimary || hasValues;
+	const isLocked = filterInView?.isLocked;
+	const hasValues = ! isLocked && filterInView?.value !== undefined;
+	const canResetOrRemove = ! isLocked && ( ! isPrimary || hasValues );
 	return (
 		<Dropdown
 			defaultOpen={ openedFilter === filter.field }
@@ -523,17 +524,26 @@ export default function Filter( {
 								{
 									'has-reset': canResetOrRemove,
 									'has-values': hasValues,
+									'is-not-clickable': isLocked,
 								}
 							) }
 							role="button"
-							tabIndex={ 0 }
-							onClick={ onToggle }
+							tabIndex={ isLocked ? -1 : 0 }
+							onClick={ () => {
+								if ( ! isLocked ) {
+									onToggle();
+								}
+							} }
 							onKeyDown={ ( event ) => {
-								if ( [ ENTER, SPACE ].includes( event.key ) ) {
+								if (
+									! isLocked &&
+									[ ENTER, SPACE ].includes( event.key )
+								) {
 									onToggle();
 									event.preventDefault();
 								}
 							} }
+							aria-disabled={ isLocked }
 							aria-pressed={ isOpen }
 							aria-expanded={ isOpen }
 							ref={ toggleRef }

package/src/components/dataviews-filters/index.tsx

@@ -36,6 +36,10 @@ export function useFilters( fields: NormalizedField< any >[], view: View ) {
 
 			const operators = field.filterBy.operators;
 			const isPrimary = !! field.filterBy?.isPrimary;
+			const isLocked =
+				view.filters?.some(
+					( f ) => f.field === field.id && !! f.isLocked
+				) ?? false;
 			filters.push( {
 				field: field.id,
 				name: field.label,
@@ -45,6 +49,7 @@ export function useFilters( fields: NormalizedField< any >[], view: View ) {
 				),
 				operators,
 				isVisible:
+					isLocked ||
 					isPrimary ||
 					!! view.filters?.some(
 						( f ) =>
@@ -52,11 +57,21 @@ export function useFilters( fields: NormalizedField< any >[], view: View ) {
 							ALL_OPERATORS.includes( f.operator )
 					),
 				isPrimary,
+				isLocked,
 			} );
 		} );
-		// Sort filters by primary property. We need the primary filters to be first.
-		// Then we sort by name.
+
+		// Sort filters by:
+		// - locked filters go first
+		// - primary filters go next
+		// - then, sort by name
 		filters.sort( ( a, b ) => {
+			if ( a.isLocked && ! b.isLocked ) {
+				return -1;
+			}
+			if ( ! a.isLocked && b.isLocked ) {
+				return 1;
+			}
 			if ( a.isPrimary && ! b.isPrimary ) {
 				return -1;
 			}

package/src/components/dataviews-filters/input-widget.tsx

@@ -62,7 +62,13 @@ export default function InputWidget( {
 							..._filter,
 							operator:
 								currentFilter.operator || filter.operators[ 0 ],
-							value: nextValue,
+							// Consider empty strings as undefined:
+							//
+							// - undefined as value means the filter is unset: the filter widget displays no value and the search returns all records
+							// - empty string as value means "search empty string": returns only the records that have an empty string as value
+							//
+							// In practice, this means the filter will not be able to find an empty string as the value.
+							value: nextValue === '' ? undefined : nextValue,
 					  }
 					: _filter
 			),