@wordpress/dataviews 4.21.0 → 5.0.0

package/src/dataviews-layouts/table/index.tsx

@@ -2,17 +2,25 @@
  * External dependencies
  */
 import clsx from 'clsx';
+import type { ComponentProps, ReactElement } from 'react';
 
 /**
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
 import { Spinner } from '@wordpress/components';
-import { useEffect, useId, useRef, useState } from '@wordpress/element';
+import {
+	useContext,
+	useEffect,
+	useId,
+	useRef,
+	useState,
+} from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
+import DataViewsContext from '../../components/dataviews-context';
 import DataViewsSelectionCheckbox from '../../components/dataviews-selection-checkbox';
 import ItemActions from '../../components/dataviews-item-actions';
 import { sortValues } from '../../constants';
@@ -30,11 +38,13 @@ import type {
 import type { SetSelection } from '../../private-types';
 import ColumnHeaderMenu from './column-header-menu';
 import ColumnPrimary from './column-primary';
+import { useIsHorizontalScrollEnd } from './use-is-horizontal-scroll-end';
 
 interface TableColumnFieldProps< Item > {
 	fields: NormalizedField< Item >[];
 	column: string;
 	item: Item;
+	align?: 'start' | 'center' | 'end';
 }
 
 interface TableRowProps< Item > {
@@ -53,12 +63,19 @@ interface TableRowProps< Item > {
 	onChangeSelection: SetSelection;
 	isItemClickable: ( item: Item ) => boolean;
 	onClickItem?: ( item: Item ) => void;
+	renderItemLink?: (
+		props: {
+			item: Item;
+		} & ComponentProps< 'a' >
+	) => ReactElement;
+	isActionsColumnSticky?: boolean;
 }
 
 function TableColumnField< Item >( {
 	item,
 	fields,
 	column,
+	align,
 }: TableColumnFieldProps< Item > ) {
 	const field = fields.find( ( f ) => f.id === column );
 
@@ -66,9 +83,14 @@ function TableColumnField< Item >( {
 		return null;
 	}
 
+	const className = clsx( 'dataviews-view-table__cell-content-wrapper', {
+		'dataviews-view-table__cell-align-end': align === 'end',
+		'dataviews-view-table__cell-align-center': align === 'center',
+	} );
+
 	return (
-		<div className="dataviews-view-table__cell-content-wrapper">
-			<field.render { ...{ item } } />
+		<div className={ className }>
+			<field.render item={ item } field={ field } />
 		</div>
 	);
 }
@@ -88,7 +110,9 @@ function TableRow< Item >( {
 	getItemId,
 	isItemClickable,
 	onClickItem,
+	renderItemLink,
 	onChangeSelection,
+	isActionsColumnSticky,
 }: TableRowProps< Item > ) {
 	const hasPossibleBulkAction = useHasAPossibleBulkAction( actions, item );
 	const isSelected = hasPossibleBulkAction && selection.includes( id );
@@ -165,20 +189,29 @@ function TableRow< Item >( {
 						}
 						isItemClickable={ isItemClickable }
 						onClickItem={ onClickItem }
+						renderItemLink={ renderItemLink }
 					/>
 				</td>
 			) }
 			{ columns.map( ( column: string ) => {
 				// Explicit picks the supported styles.
-				const { width, maxWidth, minWidth } =
+				const { width, maxWidth, minWidth, align } =
 					view.layout?.styles?.[ column ] ?? {};
 
 				return (
-					<td key={ column } style={ { width, maxWidth, minWidth } }>
+					<td
+						key={ column }
+						style={ {
+							width,
+							maxWidth,
+							minWidth,
+						} }
+					>
 						<TableColumnField
 							fields={ fields }
 							item={ item }
 							column={ column }
+							align={ align }
 						/>
 					</td>
 				);
@@ -192,7 +225,11 @@ function TableRow< Item >( {
 
 				/* eslint-disable jsx-a11y/no-noninteractive-element-interactions, jsx-a11y/click-events-have-key-events */
 				<td
-					className="dataviews-view-table__actions-column"
+					className={ clsx( 'dataviews-view-table__actions-column', {
+						'dataviews-view-table__actions-column--sticky': true,
+						'dataviews-view-table__actions-column--stuck':
+							isActionsColumnSticky,
+					} ) }
 					onClick={ ( e ) => e.stopPropagation() }
 				>
 					<ItemActions item={ item } actions={ actions } />
@@ -216,8 +253,11 @@ function ViewTable< Item >( {
 	setOpenedFilter,
 	onClickItem,
 	isItemClickable,
+	renderItemLink,
 	view,
+	className,
 }: ViewTableProps< Item > ) {
+	const { containerRef } = useContext( DataViewsContext );
 	const headerMenuRefs = useRef<
 		Map< string, { node: HTMLButtonElement; fallback: string } >
 	>( new Map() );
@@ -235,6 +275,11 @@ function ViewTable< Item >( {
 
 	const tableNoticeId = useId();
 
+	const isHorizontalScrollEnd = useIsHorizontalScrollEnd( {
+		scrollContainerRef: containerRef,
+		enabled: !! actions?.length,
+	} );
+
 	if ( nextHeaderMenuToFocus ) {
 		// If we need to force focus, we short-circuit rendering here
 		// to prevent any additional work while we handle that.
@@ -281,7 +326,7 @@ function ViewTable< Item >( {
 	return (
 		<>
 			<table
-				className={ clsx( 'dataviews-view-table', {
+				className={ clsx( 'dataviews-view-table', className, {
 					[ `has-${ view.layout?.density }-density` ]:
 						view.layout?.density &&
 						[ 'compact', 'comfortable' ].includes(
@@ -328,12 +373,17 @@ function ViewTable< Item >( {
 						) }
 						{ columns.map( ( column, index ) => {
 							// Explicit picks the supported styles.
-							const { width, maxWidth, minWidth } =
+							const { width, maxWidth, minWidth, align } =
 								view.layout?.styles?.[ column ] ?? {};
 							return (
 								<th
 									key={ column }
-									style={ { width, maxWidth, minWidth } }
+									style={ {
+										width,
+										maxWidth,
+										minWidth,
+										textAlign: align,
+									} }
 									aria-sort={
 										view.sort?.direction &&
 										view.sort?.field === column
@@ -355,7 +405,17 @@ function ViewTable< Item >( {
 							);
 						} ) }
 						{ !! actions?.length && (
-							<th className="dataviews-view-table__actions-column">
+							<th
+								className={ clsx(
+									'dataviews-view-table__actions-column',
+									{
+										'dataviews-view-table__actions-column--sticky':
+											true,
+										'dataviews-view-table__actions-column--stuck':
+											! isHorizontalScrollEnd,
+									}
+								) }
+							>
 								<span className="dataviews-view-table-header">
 									{ __( 'Actions' ) }
 								</span>
@@ -387,7 +447,11 @@ function ViewTable< Item >( {
 								getItemId={ getItemId }
 								onChangeSelection={ onChangeSelection }
 								onClickItem={ onClickItem }
+								renderItemLink={ renderItemLink }
 								isItemClickable={ isItemClickable }
+								isActionsColumnSticky={
+									! isHorizontalScrollEnd
+								}
 							/>
 						) ) }
 				</tbody>

package/src/dataviews-layouts/table/style.scss

@@ -22,6 +22,25 @@
 			text-align: right;
 		}
 
+		&.dataviews-view-table__actions-column--sticky {
+			position: sticky;
+			right: 0;
+			background-color: $white;
+		}
+
+		&.dataviews-view-table__actions-column--stuck {
+			&::after {
+				display: block;
+				content: "";
+				position: absolute;
+				top: 0;
+				bottom: 0;
+				left: 0;
+				width: 1px;
+				background-color: $gray-100;
+			}
+		}
+
 		&.dataviews-view-table__checkbox-column {
 			padding-right: 0;
 			width: 1%;
@@ -52,7 +71,8 @@
 			border-bottom: 0;
 		}
 
-		&.is-hovered {
+		&.is-hovered,
+		&.is-hovered .dataviews-view-table__actions-column--sticky {
 			background-color: #f8f8f8;
 		}
 
@@ -99,6 +119,14 @@
 			&:hover {
 				background-color: rgba(var(--wp-admin-theme-color--rgb), 0.08);
 			}
+
+			.dataviews-view-table__actions-column--sticky {
+				background-color: color-mix(in srgb, rgb(var(--wp-admin-theme-color--rgb)) 4%, $white);
+			}
+
+			&:hover .dataviews-view-table__actions-column--sticky {
+				background-color: color-mix(in srgb, rgb(var(--wp-admin-theme-color--rgb)) 8%, $white);
+			}
 		}
 	}
 	thead {
@@ -131,6 +159,14 @@
 			min-height: $grid-unit-40;
 			display: flex;
 			align-items: center;
+
+			&.dataviews-view-table__cell-align-end {
+				justify-content: flex-end;
+			}
+
+			&.dataviews-view-table__cell-align-center {
+				justify-content: center;
+			}
 		}
 
 		.components-v-stack > .dataviews-view-table__cell-content-wrapper:not(:first-child) {

package/src/dataviews-layouts/table/use-is-horizontal-scroll-end.ts

@@ -0,0 +1,82 @@
+/**
+ * External dependencies
+ */
+import type { MutableRefObject } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useDebounce } from '@wordpress/compose';
+import { useCallback, useEffect, useState } from '@wordpress/element';
+import { isRTL } from '@wordpress/i18n';
+
+const isScrolledToEnd = ( element: Element ) => {
+	if ( isRTL() ) {
+		const scrollLeft = Math.abs( element.scrollLeft );
+		return scrollLeft <= 1;
+	}
+
+	return element.scrollLeft + element.clientWidth >= element.scrollWidth - 1;
+};
+
+/**
+ * A hook to check if a given scroll container has reached the horizontal scroll end.
+ *
+ * The current way receives "refs" as arguments, but it lacks a mechanism to detect when a ref has changed.
+ * As a result, when the "ref" is updated and attached to a new div, the computation should trigger again.
+ * However, this isn't possible in the current setup because the hook is unaware that the ref has changed.
+ *
+ * See https://github.com/Automattic/wp-calypso/pull/103005#discussion_r2077567912.
+ *
+ * @param {Object}                                  params                    The parameters for the hook.
+ * @param {MutableRefObject<HTMLDivElement | null>} params.scrollContainerRef The ref to the scroll container element.
+ * @param {boolean}                                 [params.enabled=false]    Whether the hook is enabled.
+ * @return {boolean} - Returns true if the scroll container is scrolled to the end or false otherwise.
+ */
+export function useIsHorizontalScrollEnd( {
+	scrollContainerRef,
+	enabled = false,
+}: {
+	scrollContainerRef: React.MutableRefObject< HTMLDivElement | null >;
+	enabled?: boolean;
+} ): boolean {
+	const [ isHorizontalScrollEnd, setIsHorizontalScrollEnd ] =
+		useState( false );
+
+	const handleIsHorizontalScrollEnd = useDebounce(
+		useCallback( () => {
+			const scrollContainer = scrollContainerRef.current;
+			if ( scrollContainer ) {
+				setIsHorizontalScrollEnd( isScrolledToEnd( scrollContainer ) );
+			}
+		}, [ scrollContainerRef, setIsHorizontalScrollEnd ] ),
+		200
+	);
+
+	useEffect( () => {
+		if (
+			typeof window === 'undefined' ||
+			! enabled ||
+			! scrollContainerRef.current
+		) {
+			return () => {};
+		}
+
+		handleIsHorizontalScrollEnd();
+		scrollContainerRef.current.addEventListener(
+			'scroll',
+			handleIsHorizontalScrollEnd
+		);
+		window.addEventListener( 'resize', handleIsHorizontalScrollEnd );
+
+		return () => {
+			scrollContainerRef.current?.removeEventListener(
+				'scroll',
+				handleIsHorizontalScrollEnd
+			);
+			window.removeEventListener( 'resize', handleIsHorizontalScrollEnd );
+		};
+	}, [ scrollContainerRef, enabled ] );
+
+	return isHorizontalScrollEnd;
+}

package/src/dataviews-layouts/utils/item-click-wrapper.tsx

@@ -0,0 +1,93 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode, ReactElement, ComponentProps } from 'react';
+
+function getClickableItemProps< Item >( {
+	item,
+	isItemClickable,
+	onClickItem,
+	className,
+}: {
+	item: Item;
+	isItemClickable: ( item: Item ) => boolean;
+	onClickItem?: ( item: Item ) => void;
+	className?: string;
+} ) {
+	if ( ! isItemClickable( item ) || ! onClickItem ) {
+		return { className };
+	}
+
+	return {
+		className: className
+			? `${ className } ${ className }--clickable`
+			: undefined,
+		role: 'button',
+		tabIndex: 0,
+		onClick: ( event: React.MouseEvent ) => {
+			// Prevents onChangeSelection from triggering.
+			event.stopPropagation();
+			onClickItem( item );
+		},
+		onKeyDown: ( event: React.KeyboardEvent ) => {
+			if (
+				event.key === 'Enter' ||
+				event.key === '' ||
+				event.key === ' '
+			) {
+				// Prevents onChangeSelection from triggering.
+				event.stopPropagation();
+				onClickItem( item );
+			}
+		},
+	};
+}
+
+export function ItemClickWrapper< Item >( {
+	item,
+	isItemClickable,
+	onClickItem,
+	renderItemLink,
+	className,
+	children,
+	...extraProps
+}: {
+	item: Item;
+	isItemClickable: ( item: Item ) => boolean;
+	onClickItem?: ( item: Item ) => void;
+	renderItemLink?: (
+		props: {
+			item: Item;
+		} & ComponentProps< 'a' >
+	) => ReactElement;
+	className?: string;
+	children: ReactNode;
+} ) {
+	if ( ! isItemClickable( item ) ) {
+		return children;
+	}
+
+	// If we have a renderItemLink, use it
+	if ( renderItemLink ) {
+		return renderItemLink( {
+			item,
+			className: `${ className } ${ className }--clickable`,
+			...extraProps,
+			children,
+		} );
+	}
+
+	// Otherwise use the classic click handler approach
+	const clickProps = getClickableItemProps( {
+		item,
+		isItemClickable,
+		onClickItem,
+		className,
+	} );
+
+	return (
+		<div { ...clickProps } { ...extraProps }>
+			{ children }
+		</div>
+	);
+}

package/src/field-types/array.tsx

@@ -0,0 +1,75 @@
+/**
+ * Internal dependencies
+ */
+import type {
+	DataViewRenderFieldProps,
+	SortDirection,
+	ValidationContext,
+	FieldTypeDefinition,
+} from '../types';
+import {
+	OPERATOR_IS_ALL,
+	OPERATOR_IS_ANY,
+	OPERATOR_IS_NONE,
+	OPERATOR_IS_NOT_ALL,
+} from '../constants';
+
+// Sort arrays by length, then alphabetically by joined string
+function sort( valueA: any, valueB: any, direction: SortDirection ) {
+	const arrA = Array.isArray( valueA ) ? valueA : [];
+	const arrB = Array.isArray( valueB ) ? valueB : [];
+	if ( arrA.length !== arrB.length ) {
+		return direction === 'asc'
+			? arrA.length - arrB.length
+			: arrB.length - arrA.length;
+	}
+
+	const joinedA = arrA.join( ',' );
+	const joinedB = arrB.join( ',' );
+	return direction === 'asc'
+		? joinedA.localeCompare( joinedB )
+		: joinedB.localeCompare( joinedA );
+}
+
+function isValid( value: any, context?: ValidationContext ) {
+	if ( ! Array.isArray( value ) ) {
+		return false;
+	}
+
+	// Only allow strings for now. Can be extended to other types in the future.
+	if ( ! value.every( ( v ) => typeof v === 'string' ) ) {
+		return false;
+	}
+
+	if ( context?.elements ) {
+		const validValues = context.elements.map( ( f ) => f.value );
+		if ( ! value.every( ( v ) => validValues.includes( v ) ) ) {
+			return false;
+		}
+	}
+	return true;
+}
+
+function render( { item, field }: DataViewRenderFieldProps< any > ) {
+	const value = field.getValue( { item } ) || [];
+	return value.join( ', ' );
+}
+
+const arrayFieldType: FieldTypeDefinition< any > = {
+	sort,
+	isValid,
+	Edit: null, // Not implemented yet
+	render,
+	enableSorting: true,
+	filterBy: {
+		defaultOperators: [ OPERATOR_IS_ANY, OPERATOR_IS_NONE ],
+		validOperators: [
+			OPERATOR_IS_ANY,
+			OPERATOR_IS_NONE,
+			OPERATOR_IS_ALL,
+			OPERATOR_IS_NOT_ALL,
+		],
+	},
+};
+
+export default arrayFieldType;

package/src/field-types/boolean.tsx

@@ -0,0 +1,66 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import type {
+	DataViewRenderFieldProps,
+	SortDirection,
+	FieldTypeDefinition,
+} from '../types';
+import { renderFromElements } from '../utils';
+import { OPERATOR_IS, OPERATOR_IS_NOT } from '../constants';
+
+function sort( a: any, b: any, direction: SortDirection ) {
+	const boolA = Boolean( a );
+	const boolB = Boolean( b );
+
+	if ( boolA === boolB ) {
+		return 0;
+	}
+
+	// In ascending order, false comes before true
+	if ( direction === 'asc' ) {
+		return boolA ? 1 : -1;
+	}
+
+	// In descending order, true comes before false
+	return boolA ? -1 : 1;
+}
+
+function isValid( value: any ) {
+	if ( ! [ true, false, undefined ].includes( value ) ) {
+		return false;
+	}
+
+	return true;
+}
+
+export default {
+	sort,
+	isValid,
+	Edit: 'boolean',
+	render: ( { item, field }: DataViewRenderFieldProps< any > ) => {
+		if ( field.elements ) {
+			return renderFromElements( { item, field } );
+		}
+
+		if ( field.getValue( { item } ) === true ) {
+			return __( 'True' );
+		}
+
+		if ( field.getValue( { item } ) === false ) {
+			return __( 'False' );
+		}
+
+		return null;
+	},
+	enableSorting: true,
+	filterBy: {
+		defaultOperators: [ OPERATOR_IS, OPERATOR_IS_NOT ],
+		validOperators: [ OPERATOR_IS, OPERATOR_IS_NOT ],
+	},
+} satisfies FieldTypeDefinition< any >;

package/src/field-types/date.ts

@@ -0,0 +1,56 @@
+/**
+ * WordPress dependencies
+ */
+import { dateI18n, getDate, getSettings } from '@wordpress/date';
+
+/**
+ * Internal dependencies
+ */
+import type {
+	DataViewRenderFieldProps,
+	SortDirection,
+	ValidationContext,
+	FieldTypeDefinition,
+} from '../types';
+import { renderFromElements } from '../utils';
+
+const getFormattedDate = ( dateToDisplay: string | null ) =>
+	dateI18n( getSettings().formats.date, getDate( dateToDisplay ) );
+
+function sort( a: any, b: any, direction: SortDirection ) {
+	const timeA = new Date( a ).getTime();
+	const timeB = new Date( b ).getTime();
+
+	return direction === 'asc' ? timeA - timeB : timeB - timeA;
+}
+
+function isValid( value: any, context?: ValidationContext ) {
+	if ( context?.elements ) {
+		const validValues = context?.elements.map( ( f ) => f.value );
+		if ( ! validValues.includes( value ) ) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+export default {
+	sort,
+	isValid,
+	Edit: null,
+	render: ( { item, field }: DataViewRenderFieldProps< any > ) => {
+		if ( field.elements ) {
+			return renderFromElements( { item, field } );
+		}
+
+		const value = field.getValue( { item } );
+		if ( ! value ) {
+			return '';
+		}
+
+		return getFormattedDate( value );
+	},
+	enableSorting: true,
+	filterBy: false,
+} satisfies FieldTypeDefinition< any >;

package/src/field-types/datetime.tsx

@@ -1,7 +1,23 @@
 /**
  * Internal dependencies
  */
-import type { SortDirection, ValidationContext } from '../types';
+import type {
+	DataViewRenderFieldProps,
+	SortDirection,
+	ValidationContext,
+	FieldTypeDefinition,
+} from '../types';
+import { renderFromElements } from '../utils';
+import {
+	OPERATOR_ON,
+	OPERATOR_NOT_ON,
+	OPERATOR_BEFORE,
+	OPERATOR_AFTER,
+	OPERATOR_BEFORE_INC,
+	OPERATOR_AFTER_INC,
+	OPERATOR_IN_THE_PAST,
+	OPERATOR_OVER,
+} from '../constants';
 
 function sort( a: any, b: any, direction: SortDirection ) {
 	const timeA = new Date( a ).getTime();
@@ -25,4 +41,32 @@ export default {
 	sort,
 	isValid,
 	Edit: 'datetime',
-};
+	render: ( { item, field }: DataViewRenderFieldProps< any > ) => {
+		return field.elements
+			? renderFromElements( { item, field } )
+			: field.getValue( { item } );
+	},
+	enableSorting: true,
+	filterBy: {
+		defaultOperators: [
+			OPERATOR_ON,
+			OPERATOR_NOT_ON,
+			OPERATOR_BEFORE,
+			OPERATOR_AFTER,
+			OPERATOR_BEFORE_INC,
+			OPERATOR_AFTER_INC,
+			OPERATOR_IN_THE_PAST,
+			OPERATOR_OVER,
+		],
+		validOperators: [
+			OPERATOR_ON,
+			OPERATOR_NOT_ON,
+			OPERATOR_BEFORE,
+			OPERATOR_AFTER,
+			OPERATOR_BEFORE_INC,
+			OPERATOR_AFTER_INC,
+			OPERATOR_IN_THE_PAST,
+			OPERATOR_OVER,
+		],
+	},
+} satisfies FieldTypeDefinition< any >;