@wordpress/dataviews 4.22.0 → 5.0.1-next.719a03cbe.0

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,190 @@ 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 ] }
+		/>
+	);
+};

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;
+}

package/src/components/dataviews/style.scss

@@ -96,3 +96,30 @@
 	}
 	@include link-reset();
 }
+
+/**
+ * Applying a consistent 24px padding when DataViews are placed within cards.
+ */
+.components-card__body:has(> .dataviews-wrapper) {
+	padding: $grid-unit-10 0 0;
+	overflow: hidden; // Prevent cells with white backgrounds overflowing the card
+
+	.dataviews__view-actions,
+	.dataviews-filters__container,
+	.dataviews-footer,
+	.dataviews-view-grid,
+	.dataviews-loading,
+	.dataviews-no-results {
+		padding-inline: $grid-unit-30;
+	}
+
+	.dataviews-view-table tr td:first-child,
+	.dataviews-view-table tr th:first-child {
+		padding-inline-start: $grid-unit-30;
+	}
+
+	.dataviews-view-table tr td:last-child,
+	.dataviews-view-table tr th:last-child {
+		padding-inline-end: $grid-unit-30;
+	}
+}

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

@@ -1,12 +1,23 @@
+/**
+ * External dependencies
+ */
+import type { ComponentProps, ReactElement } from 'react';
+
 /**
  * WordPress dependencies
  */
-import { createContext } from '@wordpress/element';
+import { createContext, createRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
-import type { View, Action, NormalizedField } from '../../types';
+import type {
+	View,
+	Action,
+	NormalizedField,
+	SupportedLayouts,
+	NormalizedFilter,
+} from '../../types';
 import type { SetSelection } from '../../private-types';
 import { LAYOUT_TABLE } from '../../constants';
 
@@ -28,8 +39,19 @@ type DataViewsContextType< Item > = {
 	getItemId: ( item: Item ) => string;
 	getItemLevel?: ( item: Item ) => number;
 	onClickItem?: ( item: Item ) => void;
+	renderItemLink?: (
+		props: {
+			item: Item;
+		} & ComponentProps< 'a' >
+	) => ReactElement;
 	isItemClickable: ( item: Item ) => boolean;
 	containerWidth: number;
+	containerRef: React.MutableRefObject< HTMLDivElement | null >;
+	defaultLayouts: SupportedLayouts;
+	filters: NormalizedFilter[];
+	isShowingFilter: boolean;
+	setIsShowingFilter: ( value: boolean ) => void;
+	perPageSizes?: [ number, number, number, number ];
 };
 
 const DataViewsContext = createContext< DataViewsContextType< any > >( {
@@ -47,7 +69,13 @@ const DataViewsContext = createContext< DataViewsContextType< any > >( {
 	openedFilter: null,
 	getItemId: ( item ) => item.id,
 	isItemClickable: () => true,
+	renderItemLink: undefined,
 	containerWidth: 0,
+	containerRef: createRef(),
+	defaultLayouts: { list: {}, grid: {}, table: {} },
+	filters: [],
+	isShowingFilter: false,
+	setIsShowingFilter: () => {},
 } );
 
 export default DataViewsContext;