@wordpress/dataviews 4.21.0 → 5.0.0

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

@@ -29,121 +29,157 @@ export type SpaceObject = {
 	description: string;
 	image: string;
 	type: string;
+	isPlanet: boolean;
 	categories: string[];
 	satellites: number;
 	date: string;
+	datetime: string;
+	email: string;
 };
 
 export const data: SpaceObject[] = [
 	{
 		id: 1,
-		title: 'Apollo',
-		description: 'Apollo description',
-		image: 'https://live.staticflickr.com/5725/21726228300_51333bd62c_b.jpg',
-		type: 'Not a planet',
-		categories: [ 'Space', 'NASA' ],
+		title: 'Moon',
+		description: "Earth's satellite",
+		image: 'https://live.staticflickr.com/7398/9458193857_e1256123e3_z.jpg',
+		type: 'Satellite',
+		isPlanet: false,
+		categories: [ 'Solar system', 'Satellite', 'Earth', 'Moon' ],
 		satellites: 0,
-		date: '2021-01-01T00:00:00Z',
+		date: '2021-01-01',
+		datetime: '2021-01-01T14:30:00Z',
+		email: 'moon@example.com',
 	},
 	{
 		id: 2,
-		title: 'Space',
-		description: 'Space description',
-		image: 'https://live.staticflickr.com/5678/21911065441_92e2d44708_b.jpg',
-		type: 'Not a planet',
-		categories: [ 'Space' ],
+		title: 'Io',
+		description: 'Moon of Jupiter',
+		image: 'https://live.staticflickr.com/5482/9460973502_07e8ab81fe_z.jpg',
+		type: 'Satellite',
+		isPlanet: false,
+		categories: [ 'Solar system', 'Satellite', 'Jupiter', 'Moon' ],
 		satellites: 0,
-		date: '2019-01-02T00:00:00Z',
+		date: '2019-01-02',
+		datetime: '2019-01-02T09:15:00Z',
+		email: 'io@example.com',
 	},
 	{
 		id: 3,
-		title: 'NASA',
-		description: 'NASA photo',
-		image: 'https://live.staticflickr.com/742/21712365770_8f70a2c91e_b.jpg',
-		type: 'Not a planet',
-		categories: [ 'NASA' ],
+		title: 'Europa',
+		description: 'Moon of Jupiter',
+		image: 'https://live.staticflickr.com/65535/31499273012_baf5f38cc1_z.jpg',
+		type: 'Satellite',
+		isPlanet: false,
+		categories: [ 'Solar system', 'Satellite', 'Jupiter', 'Moon' ],
 		satellites: 0,
-		date: '2025-01-03T00:00:00Z',
+		date: '2025-01-03',
+		datetime: '2025-01-03T16:45:30Z',
+		email: 'europa@example.com',
 	},
 	{
 		id: 4,
 		title: 'Neptune',
-		description: 'Neptune description',
-		image: 'https://live.staticflickr.com/5725/21726228300_51333bd62c_b.jpg',
+		description: 'Ice giant in the Solar system',
+		image: 'https://live.staticflickr.com/65535/29523683990_000ff4720c_z.jpg',
 		type: 'Ice giant',
-		categories: [ 'Space', 'Planet', 'Solar system' ],
-		satellites: 14,
-		date: '2020-01-01T00:00:00Z',
+		isPlanet: true,
+		categories: [ 'Ice giant', 'Planet', 'Solar system' ],
+		satellites: 16,
+		date: '2020-01-01',
+		datetime: '2020-01-01T11:22:15Z',
+		email: 'neptune@example.com',
 	},
 	{
 		id: 5,
 		title: 'Mercury',
-		description: 'Mercury description',
-		image: 'https://live.staticflickr.com/5725/21726228300_51333bd62c_b.jpg',
+		description: 'Terrestrial planet in the Solar system',
+		image: 'https://live.staticflickr.com/813/40199101735_e5e92ffd11_z.jpg',
 		type: 'Terrestrial',
-		categories: [ 'Space', 'Planet', 'Solar system' ],
+		isPlanet: true,
+		categories: [ 'Terrestrial', 'Planet', 'Solar system' ],
 		satellites: 0,
-		date: '2020-01-02T01:00:00Z',
+		date: '2020-01-02',
+		datetime: '2020-01-02T13:05:45Z',
+		email: 'mercury@example.com',
 	},
 	{
 		id: 6,
 		title: 'Venus',
 		description: 'La planète Vénus',
-		image: 'https://live.staticflickr.com/5725/21726228300_51333bd62c_b.jpg',
+		image: 'https://live.staticflickr.com/8025/7544560662_900e717727_z.jpg',
 		type: 'Terrestrial',
-		categories: [ 'Space', 'Planet', 'Solar system' ],
+		isPlanet: true,
+		categories: [ 'Terrestrial', 'Planet', 'Solar system' ],
 		satellites: 0,
-		date: '2020-01-02T00:00:00Z',
+		date: '2020-01-02',
+		datetime: '2020-01-02T08:30:12Z',
+		email: 'venus@example.com',
 	},
 	{
 		id: 7,
 		title: 'Earth',
-		description: 'Earth description',
-		image: 'https://live.staticflickr.com/5725/21726228300_51333bd62c_b.jpg',
+		description: 'Terrestrial planet in the Solar system',
+		image: 'https://live.staticflickr.com/3762/9460163562_964fe6af07_z.jpg',
 		type: 'Terrestrial',
-		categories: [ 'Space', 'Planet', 'Solar system' ],
+		isPlanet: true,
+		categories: [ 'Terrestrial', 'Planet', 'Solar system', 'Earth' ],
 		satellites: 1,
-		date: '2023-01-03T00:00:00Z',
+		date: '2023-01-03',
+		datetime: '2023-01-03T18:15:30Z',
+		email: 'earth@example.com',
 	},
 	{
 		id: 8,
 		title: 'Mars',
-		description: 'Mars description',
-		image: 'https://live.staticflickr.com/5725/21726228300_51333bd62c_b.jpg',
+		description: 'Terrestrial planet in the Solar system',
+		image: 'https://live.staticflickr.com/8151/7651156426_e047f4d219_z.jpg',
 		type: 'Terrestrial',
-		categories: [ 'Space', 'Planet', 'Solar system' ],
+		isPlanet: true,
+		categories: [ 'Terrestrial', 'Planet', 'Solar system' ],
 		satellites: 2,
-		date: '2020-01-01T00:00:00Z',
+		date: '2020-01-01',
+		datetime: '2020-01-01T20:45:00Z',
+		email: 'mars@example.com',
 	},
 	{
 		id: 9,
 		title: 'Jupiter',
-		description: 'Jupiter description',
-		image: 'https://live.staticflickr.com/5725/21726228300_51333bd62c_b.jpg',
+		description: 'Gas giant in the Solar system',
+		image: 'https://staging-jubilee.flickr.com/2853/9458010071_6e6fc41408_z.jpg',
 		type: 'Gas giant',
-		categories: [ 'Space', 'Planet', 'Solar system' ],
-		satellites: 95,
-		date: '2017-01-01T00:01:00Z',
+		isPlanet: true,
+		categories: [ 'Solar system', 'Planet', 'Gas giant' ],
+		satellites: 97,
+		date: '2017-01-01',
+		datetime: '2017-01-01T00:01:00Z',
+		email: 'jupiter@example.com',
 	},
 	{
 		id: 10,
 		title: 'Saturn',
-		description: 'Saturn description',
-		image: 'https://live.staticflickr.com/5725/21726228300_51333bd62c_b.jpg',
+		description: 'Gas giant in the Solar system',
+		image: 'https://live.staticflickr.com/5524/9464658509_fc2d83dff5_z.jpg',
 		type: 'Gas giant',
-		categories: [ 'Space', 'Planet', 'Solar system' ],
-		satellites: 146,
-		date: '2020-02-01T00:02:00Z',
+		isPlanet: true,
+		categories: [ 'Gas giant', 'Solar system', 'Planet' ],
+		satellites: 274,
+		date: '2020-02-01',
+		datetime: '2020-02-01T00:02:00Z',
+		email: 'saturn@example.com',
 	},
 	{
 		id: 11,
 		title: 'Uranus',
-		description: 'Uranus description',
-		image: 'https://live.staticflickr.com/5725/21726228300_51333bd62c_b.jpg',
+		description: 'Ice giant in the Solar system',
+		image: 'https://live.staticflickr.com/65535/5553350875_3072df91e2_c.jpg',
 		type: 'Ice giant',
-		categories: [ 'Space', 'Ice giant', 'Solar system' ],
+		isPlanet: true,
+		categories: [ 'Planet', 'Ice giant', 'Solar system' ],
 		satellites: 28,
-		date: '2020-03-01T00:00:00Z',
+		date: '2020-03-01',
+		datetime: '2020-03-01T10:15:20Z',
+		email: 'uranus@example.com',
 	},
 ];
 
@@ -562,7 +598,7 @@ export const themeFields: Field< Theme >[] = [
 	{
 		id: 'tags',
 		label: 'Tags',
-		render: ( { item } ) => item.tags.join( ', ' ),
+		type: 'array',
 	},
 ];
 
@@ -571,7 +607,13 @@ export const DEFAULT_VIEW = {
 	search: '',
 	page: 1,
 	perPage: 10,
-	layout: {},
+	layout: {
+		styles: {
+			satellites: {
+				align: 'end' as const,
+			},
+		},
+	},
 	filters: [],
 };
 
@@ -583,6 +625,7 @@ export const actions: Action< SpaceObject >[] = [
 		icon: trash,
 		hideModalHeader: true,
 		modalFocusOnMount: 'firstContentElement',
+		supportsBulk: true,
 		RenderModal: ( { items, closeModal } ) => {
 			return (
 				<VStack spacing="5">
@@ -620,6 +663,7 @@ export const fields: Field< SpaceObject >[] = [
 	{
 		label: 'Image',
 		id: 'image',
+		type: 'media',
 		header: (
 			<HStack spacing={ 1 } justify="start">
 				<Icon icon={ image } />
@@ -631,17 +675,25 @@ export const fields: Field< SpaceObject >[] = [
 				<img src={ item.image } alt="" style={ { width: '100%' } } />
 			);
 		},
-		enableSorting: false,
 	},
 	{
 		label: 'Title',
 		id: 'title',
+		type: 'text',
 		enableHiding: false,
 		enableGlobalSearch: true,
+		filterBy: {
+			operators: [ 'contains', 'notContains', 'startsWith' ],
+		},
 	},
 	{
 		id: 'date',
 		label: 'Date',
+		type: 'date',
+	},
+	{
+		id: 'datetime',
+		label: 'Datetime',
 		type: 'datetime',
 	},
 	{
@@ -649,11 +701,23 @@ export const fields: Field< SpaceObject >[] = [
 		id: 'type',
 		enableHiding: false,
 		elements: [
-			{ value: 'Not a planet', label: 'Not a planet' },
+			{ value: 'Satellite', label: 'Satellite' },
 			{ value: 'Ice giant', label: 'Ice giant' },
 			{ value: 'Terrestrial', label: 'Terrestrial' },
 			{ value: 'Gas giant', label: 'Gas giant' },
 		],
+		filterBy: {
+			operators: [ 'is', 'isNot' ],
+		},
+	},
+	{
+		id: 'isPlanet',
+		label: 'Is Planet',
+		type: 'boolean',
+		elements: [
+			{ value: true, label: 'True' },
+			{ value: false, label: 'False' },
+		],
 	},
 	{
 		label: 'Satellites',
@@ -664,8 +728,15 @@ export const fields: Field< SpaceObject >[] = [
 	{
 		label: 'Description',
 		id: 'description',
+		type: 'text',
 		enableSorting: false,
 		enableGlobalSearch: true,
+		filterBy: false,
+	},
+	{
+		label: 'Email',
+		id: 'email',
+		type: 'email',
 	},
 	{
 		label: 'Categories',
@@ -677,21 +748,16 @@ export const fields: Field< SpaceObject >[] = [
 			</HStack>
 		),
 		elements: [
-			{ value: 'Space', label: 'Space' },
-			{ value: 'NASA', label: 'NASA' },
-			{ value: 'Planet', label: 'Planet' },
 			{ value: 'Solar system', label: 'Solar system' },
+			{ value: 'Satellite', label: 'Satellite' },
+			{ value: 'Moon', label: 'Moon' },
+			{ value: 'Earth', label: 'Earth' },
+			{ value: 'Jupiter', label: 'Jupiter' },
+			{ value: 'Planet', label: 'Planet' },
 			{ value: 'Ice giant', label: 'Ice giant' },
+			{ value: 'Terrestrial', label: 'Terrestrial' },
+			{ value: 'Gas giant', label: 'Gas giant' },
 		],
-		filterBy: {
-			operators: [ 'isAny', 'isNone', 'isAll', 'isNotAll' ],
-		},
-		getValue: ( { item } ) => {
-			return item.categories;
-		},
-		render: ( { item } ) => {
-			return item.categories.join( ',' );
-		},
-		enableSorting: false,
+		type: 'array',
 	},
 ];

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

@@ -1,13 +1,39 @@
+/**
+ * External dependencies
+ */
+import type { Meta } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
-import { useState, useMemo } from '@wordpress/element';
+import {
+	useState,
+	useMemo,
+	createInterpolateElement,
+} from '@wordpress/element';
+import {
+	Card,
+	CardHeader,
+	CardBody,
+	__experimentalGrid as Grid,
+	__experimentalHeading as Heading,
+	__experimentalText as Text,
+	__experimentalHStack as HStack,
+	__experimentalVStack as VStack,
+} from '@wordpress/components';
+import { __, _n } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
  */
 import DataViews from '../index';
-import { DEFAULT_VIEW, actions, data, fields } from './fixtures';
+import {
+	DEFAULT_VIEW,
+	actions,
+	data,
+	fields,
+	type SpaceObject,
+} from './fixtures';
 import { LAYOUT_GRID, LAYOUT_LIST, LAYOUT_TABLE } from '../../../constants';
 import { filterSortAndPaginate } from '../../../filter-and-sort-data-view';
 import type { View } from '../../../types';
@@ -17,7 +43,8 @@ import './style.css';
 const meta = {
 	title: 'DataViews/DataViews',
 	component: DataViews,
-};
+} as Meta< typeof DataViews >;
+
 export default meta;
 
 const defaultLayouts = {
@@ -46,10 +73,17 @@ export const Default = () => {
 			fields={ fields }
 			onChangeView={ setView }
 			actions={ actions }
-			onClickItem={ ( item ) => {
-				// eslint-disable-next-line no-alert
-				alert( 'Clicked: ' + item.title );
-			} }
+			renderItemLink={ ( { item, ...props }: { item: SpaceObject } ) => (
+				<button
+					style={ { background: 'none', border: 'none', padding: 0 } }
+					onClick={ ( e ) => {
+						e.stopPropagation();
+						// eslint-disable-next-line no-alert
+						alert( 'Clicked: ' + item.title );
+					} }
+					{ ...props }
+				/>
+			) }
 			isItemClickable={ () => true }
 			defaultLayouts={ defaultLayouts }
 		/>
@@ -105,3 +139,227 @@ export const FieldsNoSortableNoHidable = () => {
 		/>
 	);
 };
+
+/**
+ * Custom composition example
+ */
+function PlanetOverview( { planets }: { planets: SpaceObject[] } ) {
+	const moons = planets.reduce( ( sum, item ) => sum + item.satellites, 0 );
+
+	return (
+		<>
+			<Heading className="free-composition-heading" level={ 2 }>
+				{ __( 'Solar System numbers' ) }
+			</Heading>
+			<Grid
+				templateColumns="repeat(auto-fit, minmax(330px, 1fr))"
+				align="flex-start"
+				className="free-composition-header"
+			>
+				<Card variant="secondary">
+					<CardBody>
+						<VStack>
+							<Text size={ 18 } as="p">
+								{ createInterpolateElement(
+									_n(
+										'<PlanetsNumber /> planet',
+										'<PlanetsNumber /> planets',
+										planets.length
+									),
+									{
+										PlanetsNumber: (
+											<strong>{ planets.length } </strong>
+										),
+									}
+								) }
+							</Text>
+
+							<Text size={ 18 } as="p">
+								{ createInterpolateElement(
+									_n(
+										'<SatellitesNumber /> moon',
+										'<SatellitesNumber /> moons',
+										moons
+									),
+									{
+										SatellitesNumber: (
+											<strong>{ moons } </strong>
+										),
+									}
+								) }
+							</Text>
+						</VStack>
+					</CardBody>
+				</Card>
+
+				<VStack>
+					<HStack justify="start">
+						<DataViews.FiltersToggle />
+						<DataViews.Search label={ __( 'moons by planet' ) } />
+					</HStack>
+					<DataViews.Filters />
+				</VStack>
+
+				<VStack>
+					<HStack justify="end">
+						<DataViews.Pagination />
+						<DataViews.ViewConfig />
+						<DataViews.LayoutSwitcher />
+					</HStack>
+
+					<DataViews.BulkActionToolbar />
+				</VStack>
+			</Grid>
+
+			<DataViews.Layout className="free-composition-dataviews-layout" />
+		</>
+	);
+}
+
+/**
+ * This is a basic example of using the DataViews component in
+ * a free composition mode.
+ *
+ * Unlike the default usage where DataViews renders its own UI,
+ * here we use it purely to provide context and handle data-related logic.
+ *
+ * The UI is fully custom and composed externally via the
+ * `PlanetOverview` component.
+ *
+ * In future iterations, this story will showcase more advanced compositions
+ * using built-in subcomponents like <Search />, filters,
+ * or pagination controls.
+ */
+export const FreeComposition = () => {
+	const [ view, setView ] = useState< View >( {
+		...DEFAULT_VIEW,
+		fields: [ 'categories' ],
+		titleField: 'title',
+		descriptionField: 'description',
+		mediaField: 'image',
+	} );
+
+	const { data: processedData, paginationInfo } = useMemo( () => {
+		return filterSortAndPaginate( data, view, fields );
+	}, [ view ] );
+
+	const planets = processedData.filter( ( item ) =>
+		item.categories.includes( 'Planet' )
+	);
+
+	return (
+		<div className="free-composition">
+			<DataViews
+				getItemId={ ( item ) => item.id.toString() }
+				paginationInfo={ paginationInfo }
+				data={ processedData }
+				view={ view }
+				fields={ fields }
+				actions={ actions }
+				onChangeView={ setView }
+				defaultLayouts={ {
+					table: {},
+					grid: {},
+				} }
+			>
+				<PlanetOverview planets={ planets } />
+			</DataViews>
+		</div>
+	);
+};
+
+export const WithCard = () => {
+	const [ view, setView ] = useState< View >( {
+		...DEFAULT_VIEW,
+		fields: [ 'categories' ],
+		titleField: 'title',
+		descriptionField: 'description',
+		mediaField: 'image',
+	} );
+	const { data: shownData, paginationInfo } = useMemo( () => {
+		return filterSortAndPaginate( data, view, fields );
+	}, [ view ] );
+	return (
+		<Card>
+			<CardHeader>Header</CardHeader>
+			<CardBody>
+				<DataViews
+					getItemId={ ( item ) => item.id.toString() }
+					paginationInfo={ paginationInfo }
+					data={ shownData }
+					view={ view }
+					fields={ fields }
+					onChangeView={ setView }
+					actions={ actions.filter(
+						( action ) => ! action.supportsBulk
+					) }
+					defaultLayouts={ defaultLayouts }
+				/>
+			</CardBody>
+		</Card>
+	);
+};
+
+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 = () => {
+	const [ view, setView ] = useState< View >( {
+		type: LAYOUT_GRID,
+		search: '',
+		page: 1,
+		perPage: 20,
+		filters: [],
+		fields: [ 'satellites' ],
+		titleField: 'title',
+		descriptionField: 'description',
+		mediaField: 'image',
+		groupByField: 'type',
+		layout: {
+			badgeFields: [ 'satellites' ],
+		},
+	} );
+	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 }
+			defaultLayouts={ {
+				[ LAYOUT_GRID ]: {},
+				[ LAYOUT_LIST ]: {},
+				[ LAYOUT_TABLE ]: {},
+			} }
+		/>
+	);
+};

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

@@ -1,4 +1,25 @@
 .theme-field-description {
-    text-wrap: balance;
-    text-wrap: pretty;
-}
+	text-wrap: balance;
+	text-wrap: pretty;
+}
+
+.free-composition {
+	height: 600px;
+	overflow: auto;
+}
+
+.free-composition-heading,
+.free-composition-header {
+	padding: 16px 48px;
+}
+
+.free-composition-heading {
+	position: sticky;
+	top: 0;
+	z-index: 2;
+	background-color: #fff;
+}
+
+.free-composition-dataviews-layout thead {
+	inset-block-start: 67px;
+}