@wordpress/dataviews 4.22.0 → 5.0.0

package/src/test/normalize-fields.ts

@@ -42,4 +42,159 @@ describe( 'normalizeFields: default getValue', () => {
 			expect( result ).toBe( 'value' );
 		} );
 	} );
+	describe( 'filterBy', () => {
+		it( 'returns the default field type definition if undefined for untyped field', () => {
+			const fields: Field< {} >[] = [
+				{
+					id: 'user',
+				},
+			];
+			const normalizedFields = normalizeFields( fields );
+			const result = normalizedFields[ 0 ].filterBy;
+			expect( result ).toStrictEqual( { operators: [ 'is', 'isNot' ] } );
+		} );
+		it( 'returns the default field type definition if undefined for untyped field (for primary filters)', () => {
+			const fields: Field< {} >[] = [
+				{
+					id: 'user',
+					filterBy: {
+						isPrimary: true,
+					},
+				},
+			];
+			const normalizedFields = normalizeFields( fields );
+			const result = normalizedFields[ 0 ].filterBy;
+			expect( result ).toStrictEqual( {
+				isPrimary: true,
+				operators: [ 'is', 'isNot' ],
+			} );
+		} );
+
+		it( 'returns the field type definition for typed fields', () => {
+			const fields: Field< {} >[] = [
+				{
+					id: 'user',
+					type: 'integer',
+				},
+			];
+			const normalizedFields = normalizeFields( fields );
+			const result = normalizedFields[ 0 ].filterBy;
+			expect( result ).toStrictEqual( {
+				operators: [
+					'is',
+					'isNot',
+					'lessThan',
+					'greaterThan',
+					'lessThanOrEqual',
+					'greaterThanOrEqual',
+					'between',
+				],
+			} );
+		} );
+
+		it( 'returns the field type definition for typed fields (for primary filters)', () => {
+			const fields: Field< {} >[] = [
+				{
+					id: 'user',
+					type: 'integer',
+					filterBy: {
+						isPrimary: true,
+					},
+				},
+			];
+			const normalizedFields = normalizeFields( fields );
+			const result = normalizedFields[ 0 ].filterBy;
+			expect( result ).toStrictEqual( {
+				isPrimary: true,
+				operators: [
+					'is',
+					'isNot',
+					'lessThan',
+					'greaterThan',
+					'lessThanOrEqual',
+					'greaterThanOrEqual',
+					'between',
+				],
+			} );
+		} );
+
+		it( 'returns false if is false', () => {
+			const fields: Field< {} >[] = [
+				{
+					id: 'user',
+					filterBy: false,
+				},
+			];
+			const normalizedFields = normalizeFields( fields );
+			const result = normalizedFields[ 0 ].filterBy;
+			expect( result ).toBe( false );
+		} );
+
+		it( 'returns the config if it provides one', () => {
+			const fields: Field< {} >[] = [
+				{
+					id: 'user',
+					filterBy: {
+						isPrimary: true,
+						operators: [ 'is', 'isNot' ],
+					},
+				},
+			];
+			const normalizedFields = normalizeFields( fields );
+			const result = normalizedFields[ 0 ].filterBy;
+			expect( result ).toStrictEqual( {
+				isPrimary: true,
+				operators: [ 'is', 'isNot' ],
+			} );
+		} );
+
+		it( 'returns false if the none of the operators are valid for the type', () => {
+			const fields: Field< {} >[] = [
+				{
+					id: 'user',
+					filterBy: {
+						// @ts-ignore
+						operators: [ 'invalid', 'operator' ],
+					},
+				},
+			];
+			const normalizedFields = normalizeFields( fields );
+			const result = normalizedFields[ 0 ].filterBy;
+			expect( result ).toBe( false );
+		} );
+
+		it( 'returns false if the list of operators is empty', () => {
+			const fields: Field< {} >[] = [
+				{
+					id: 'user',
+					filterBy: {
+						operators: [],
+					},
+				},
+			];
+			const normalizedFields = normalizeFields( fields );
+			const result = normalizedFields[ 0 ].filterBy;
+			expect( result ).toBe( false );
+		} );
+
+		it( 'removes invalid operators for the type', () => {
+			const fields: Field< {} >[] = [
+				{
+					id: 'user',
+					type: 'integer',
+					filterBy: {
+						isPrimary: true,
+						// @ts-ignore
+						operators: [ 'invalid', 'lessThan' ],
+					},
+				},
+			];
+			const normalizedFields = normalizeFields( fields );
+			const result = normalizedFields[ 0 ].filterBy;
+			expect( result ).toStrictEqual( {
+				isPrimary: true,
+				operators: [ 'lessThan' ],
+			} );
+		} );
+	} );
 } );

package/src/types.ts

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ReactElement, ComponentType } from 'react';
+import type { ReactElement, ComponentType, ComponentProps } from 'react';
 
 /**
  * Internal dependencies
@@ -24,7 +24,7 @@ export interface Option< Value extends any = any > {
 	description?: string;
 }
 
-interface FilterByConfig {
+export interface FilterByConfig {
 	/**
 	 * The list of operators supported by the field.
 	 */
@@ -39,15 +39,66 @@ interface FilterByConfig {
 	isPrimary?: boolean;
 }
 
+export interface NormalizedFilterByConfig {
+	/**
+	 * The list of operators supported by the field.
+	 */
+	operators: Operator[];
+
+	/**
+	 * Whether it is a primary filter.
+	 *
+	 * A primary filter is always visible and is not listed in the "Add filter" component,
+	 * except for the list layout where it behaves like a secondary filter.
+	 */
+	isPrimary?: boolean;
+}
+
+interface FilterConfigForType {
+	/**
+	 * What operators are used by default.
+	 */
+	defaultOperators: Operator[];
+
+	/**
+	 * What operators are supported by the field.
+	 */
+	validOperators: Operator[];
+}
+
 export type Operator =
 	| 'is'
 	| 'isNot'
 	| 'isAny'
 	| 'isNone'
 	| 'isAll'
-	| 'isNotAll';
-
-export type FieldType = 'text' | 'integer' | 'datetime' | 'media';
+	| 'isNotAll'
+	| 'lessThan'
+	| 'greaterThan'
+	| 'lessThanOrEqual'
+	| 'greaterThanOrEqual'
+	| 'before'
+	| 'after'
+	| 'beforeInc'
+	| 'afterInc'
+	| 'contains'
+	| 'notContains'
+	| 'startsWith'
+	| 'between'
+	| 'on'
+	| 'notOn'
+	| 'inThePast'
+	| 'over';
+
+export type FieldType =
+	| 'text'
+	| 'integer'
+	| 'datetime'
+	| 'date'
+	| 'media'
+	| 'boolean'
+	| 'email'
+	| 'array';
 
 export type ValidationContext = {
 	elements?: Option[];
@@ -70,7 +121,28 @@ export type FieldTypeDefinition< Item > = {
 	/**
 	 * Callback used to render an edit control for the field or control name.
 	 */
-	Edit: ComponentType< DataFormControlProps< Item > > | string;
+	Edit: ComponentType< DataFormControlProps< Item > > | string | null;
+
+	/**
+	 * Callback used to render the field.
+	 */
+	render: ComponentType< DataViewRenderFieldProps< Item > >;
+
+	/**
+	 * The filter config for the field.
+	 */
+	filterBy: FilterConfigForType | false;
+
+	/**
+	 * Whether the field is readOnly.
+	 * If `true`, the value will be rendered using the `render` callback.
+	 */
+	readOnly?: boolean;
+
+	/**
+	 * Whether the field is sortable.
+	 */
+	enableSorting: boolean;
 };
 
 /**
@@ -156,7 +228,13 @@ export type Field< Item > = {
 	/**
 	 * Filter config for the field.
 	 */
-	filterBy?: FilterByConfig | undefined;
+	filterBy?: FilterByConfig | false;
+
+	/**
+	 * Whether the field is readOnly.
+	 * If `true`, the value will be rendered using the `render` callback.
+	 */
+	readOnly?: boolean;
 
 	/**
 	 * Callback used to retrieve the value of the field from the item.
@@ -165,16 +243,18 @@ export type Field< Item > = {
 	getValue?: ( args: { item: Item } ) => any;
 };
 
-export type NormalizedField< Item > = Field< Item > & {
+export type NormalizedField< Item > = Omit< Field< Item >, 'Edit' > & {
 	label: string;
 	header: string | ReactElement;
 	getValue: ( args: { item: Item } ) => any;
 	render: ComponentType< DataViewRenderFieldProps< Item > >;
-	Edit: ComponentType< DataFormControlProps< Item > >;
+	Edit: ComponentType< DataFormControlProps< Item > > | null;
 	sort: ( a: Item, b: Item, direction: SortDirection ) => number;
 	isValid: ( item: Item, context?: ValidationContext ) => boolean;
 	enableHiding: boolean;
 	enableSorting: boolean;
+	filterBy: NormalizedFilterByConfig | false;
+	readOnly: boolean;
 };
 
 /**
@@ -189,10 +269,17 @@ export type DataFormControlProps< Item > = {
 	field: NormalizedField< Item >;
 	onChange: ( value: Record< string, any > ) => void;
 	hideLabelFromVision?: boolean;
+	/**
+	 * The currently selected filter operator for this field.
+	 *
+	 * Used by DataViews filters to determine which control to render based on the operator type.
+	 */
+	operator?: Operator;
 };
 
 export type DataViewRenderFieldProps< Item > = {
 	item: Item;
+	field: NormalizedField< Item >;
 };
 
 /**
@@ -332,6 +419,11 @@ interface ViewBase {
 	 * Whether to show the hierarchical levels.
 	 */
 	showLevels?: boolean;
+
+	/**
+	 * The field to group by.
+	 */
+	groupByField?: string;
 }
 
 export interface ColumnStyle {
@@ -349,6 +441,11 @@ export interface ColumnStyle {
 	 * The maximum width of the field column.
 	 */
 	minWidth?: string | number;
+
+	/**
+	 * The alignment of the field column, defaults to left.
+	 */
+	align?: 'start' | 'center' | 'end';
 }
 
 export type Density = 'compact' | 'balanced' | 'comfortable';
@@ -500,6 +597,7 @@ export interface ActionButton< Item > extends ActionBase< Item > {
 export type Action< Item > = ActionModal< Item > | ActionButton< Item >;
 
 export interface ViewBaseProps< Item > {
+	className?: string;
 	actions: Action< Item >[];
 	data: Item[];
 	fields: NormalizedField< Item >[];
@@ -511,6 +609,11 @@ export interface ViewBaseProps< Item > {
 	selection: string[];
 	setOpenedFilter: ( fieldId: string ) => void;
 	onClickItem?: ( item: Item ) => void;
+	renderItemLink?: (
+		props: {
+			item: Item;
+		} & ComponentProps< 'a' >
+	) => ReactElement;
 	isItemClickable: ( item: Item ) => boolean;
 	view: View;
 }

package/src/utils.ts

@@ -1,38 +1,15 @@
 /**
  * Internal dependencies
  */
-import {
-	ALL_OPERATORS,
-	OPERATOR_IS,
-	OPERATOR_IS_NOT,
-	OPERATOR_IS_ANY,
-	OPERATOR_IS_NONE,
-} from './constants';
-import type { NormalizedField } from './types';
-
-export function sanitizeOperators< Item >( field: NormalizedField< Item > ) {
-	let operators = field.filterBy?.operators;
-
-	// Assign default values.
-	if ( ! operators || ! Array.isArray( operators ) ) {
-		operators = [ OPERATOR_IS_ANY, OPERATOR_IS_NONE ];
-	}
-
-	// Make sure only valid operators are used.
-	operators = operators.filter( ( operator ) =>
-		ALL_OPERATORS.includes( operator )
+import type { DataViewRenderFieldProps } from './types';
+
+export function renderFromElements< Item >( {
+	item,
+	field,
+}: DataViewRenderFieldProps< Item > ) {
+	const value = field.getValue( { item } );
+	return (
+		field?.elements?.find( ( element ) => element.value === value )
+			?.label || field.getValue( { item } )
 	);
-
-	// Do not allow mixing single & multiselection operators.
-	// Remove multiselection operators if any of the single selection ones is present.
-	if (
-		operators.includes( OPERATOR_IS ) ||
-		operators.includes( OPERATOR_IS_NOT )
-	) {
-		operators = operators.filter( ( operator ) =>
-			[ OPERATOR_IS, OPERATOR_IS_NOT ].includes( operator )
-		);
-	}
-
-	return operators;
 }

package/tsconfig.json

@@ -13,11 +13,13 @@
 		{ "path": "../components" },
 		{ "path": "../compose" },
 		{ "path": "../data" },
+		{ "path": "../date" },
 		{ "path": "../element" },
 		{ "path": "../i18n" },
 		{ "path": "../icons" },
 		{ "path": "../primitives" },
 		{ "path": "../private-apis" },
+		{ "path": "../url" },
 		{ "path": "../warning" }
 	],
 	"exclude": [