@wordpress/dataviews 9.1.1-next.233ccab9b.0 → 10.0.0

package/src/types/field-api.ts

@@ -0,0 +1,381 @@
+/**
+ * External dependencies
+ */
+import type { ReactElement, ComponentType } from 'react';
+
+/**
+ * Utility type that makes all properties of T optional recursively.
+ * Used by field setValue functions to allow partial item updates.
+ */
+export type DeepPartial< T > = {
+	[ P in keyof T ]?: T[ P ] extends object ? DeepPartial< T[ P ] > : T[ P ];
+};
+
+export type SortDirection = 'asc' | 'desc';
+
+/**
+ * Generic option type.
+ */
+export interface Option< Value extends any = any > {
+	value: Value;
+	label: string;
+	description?: string;
+}
+
+export interface FilterByConfig {
+	/**
+	 * 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;
+}
+
+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'
+	| 'lessThan'
+	| 'greaterThan'
+	| 'lessThanOrEqual'
+	| 'greaterThanOrEqual'
+	| 'before'
+	| 'after'
+	| 'beforeInc'
+	| 'afterInc'
+	| 'contains'
+	| 'notContains'
+	| 'startsWith'
+	| 'between'
+	| 'on'
+	| 'notOn'
+	| 'inThePast'
+	| 'over';
+
+export type FieldType =
+	| 'text'
+	| 'integer'
+	| 'number'
+	| 'datetime'
+	| 'date'
+	| 'media'
+	| 'boolean'
+	| 'email'
+	| 'password'
+	| 'telephone'
+	| 'color'
+	| 'url'
+	| 'array';
+
+/**
+ * An abstract interface for Field based on the field type.
+ */
+export type FieldTypeDefinition< Item > = {
+	/**
+	 * Callback used to sort the field.
+	 */
+	sort: ( a: Item, b: Item, direction: SortDirection ) => number;
+
+	/**
+	 * Callback used to validate the field.
+	 */
+	isValid: Rules< Item >;
+
+	/**
+	 * Callback used to render an edit control for the field or control name.
+	 */
+	Edit:
+		| ComponentType< DataFormControlProps< Item > >
+		| string
+		| EditConfig
+		| 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;
+};
+
+export type Rules< Item > = {
+	required?: boolean;
+	elements?: boolean;
+	custom?:
+		| ( ( item: Item, field: NormalizedField< Item > ) => null | string )
+		| ( (
+				item: Item,
+				field: NormalizedField< Item >
+		  ) => Promise< null | string > );
+};
+
+/**
+ * Edit configuration for textarea controls.
+ */
+export type EditConfigTextarea = {
+	control: 'textarea';
+	/**
+	 * Number of rows for the textarea.
+	 */
+	rows?: number;
+};
+
+/**
+ * Edit configuration for text controls.
+ */
+export type EditConfigText = {
+	control: 'text';
+	/**
+	 * Prefix component to display before the input.
+	 */
+	prefix?: React.ComponentType;
+	/**
+	 * Suffix component to display after the input.
+	 */
+	suffix?: React.ComponentType;
+};
+
+/**
+ * Edit configuration for other control types (excluding 'text' and 'textarea').
+ */
+export type EditConfigGeneric = {
+	control: Exclude< FieldType, 'text' | 'textarea' >;
+};
+
+/**
+ * Edit configuration object with type-safe control options.
+ * Each control type has its own specific configuration properties.
+ */
+export type EditConfig =
+	| EditConfigTextarea
+	| EditConfigText
+	| EditConfigGeneric;
+
+/**
+ * A dataview field for a specific property of a data type.
+ */
+export type Field< Item > = {
+	/**
+	 * Type of the fields.
+	 */
+	type?: FieldType;
+
+	/**
+	 * The unique identifier of the field.
+	 */
+	id: string;
+
+	/**
+	 * The label of the field. Defaults to the id.
+	 */
+	label?: string;
+
+	/**
+	 * The header of the field. Defaults to the label.
+	 * It allows the usage of a React Element to render the field labels.
+	 */
+	header?: string | ReactElement;
+
+	/**
+	 * A description of the field.
+	 */
+	description?: string;
+
+	/**
+	 * Placeholder for the field.
+	 */
+	placeholder?: string;
+
+	/**
+	 * Callback used to render the field. Defaults to `field.getValue`.
+	 */
+	render?: ComponentType< DataViewRenderFieldProps< Item > >;
+
+	/**
+	 * Callback used to render an edit control for the field.
+	 */
+	Edit?: ComponentType< DataFormControlProps< Item > > | string | EditConfig;
+
+	/**
+	 * Callback used to sort the field.
+	 */
+	sort?: ( a: Item, b: Item, direction: SortDirection ) => number;
+
+	/**
+	 * Callback used to validate the field.
+	 */
+	isValid?: Rules< Item >;
+
+	/**
+	 * Callback used to decide if a field should be displayed.
+	 */
+	isVisible?: ( item: Item ) => boolean;
+
+	/**
+	 * Whether the field is sortable.
+	 */
+	enableSorting?: boolean;
+
+	/**
+	 * Whether the field is searchable.
+	 */
+	enableGlobalSearch?: boolean;
+
+	/**
+	 * Whether the field can be hidden in the UI.
+	 */
+	enableHiding?: boolean;
+
+	/**
+	 * The list of options to pick from when using the field as a filter.
+	 */
+	elements?: Option[];
+
+	/**
+	 * Retrieval function for elements.
+	 */
+	getElements?: () => Promise< Option[] >;
+
+	/**
+	 * Filter config for the field.
+	 */
+	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.
+	 * Defaults to `item[ field.id ]`.
+	 */
+	getValue?: ( args: { item: Item } ) => any;
+
+	/**
+	 * Callback used to set the value of the field on the item.
+	 * Used for editing operations to update field values.
+	 */
+	setValue?: ( args: { item: Item; value: any } ) => DeepPartial< Item >;
+};
+
+export type NormalizedField< Item > = Omit< Field< Item >, 'Edit' > & {
+	label: string;
+	header: string | ReactElement;
+	getValue: ( args: { item: Item } ) => any;
+	setValue: ( args: { item: Item; value: any } ) => DeepPartial< Item >;
+	render: ComponentType< DataViewRenderFieldProps< Item > >;
+	Edit: ComponentType< DataFormControlProps< Item > > | null;
+	hasElements: boolean;
+	sort: ( a: Item, b: Item, direction: SortDirection ) => number;
+	isValid: Rules< Item >;
+	enableHiding: boolean;
+	enableSorting: boolean;
+	filterBy: NormalizedFilterByConfig | false;
+	readOnly: boolean;
+};
+
+/**
+ * A collection of dataview fields for a data type.
+ */
+export type Fields< Item > = Field< Item >[];
+
+export type FieldValidity = {
+	required?: {
+		type: 'valid' | 'invalid' | 'validating';
+		message?: string;
+	};
+	elements?: {
+		type: 'valid' | 'invalid' | 'validating';
+		message: string;
+	};
+	custom?: {
+		type: 'valid' | 'invalid' | 'validating';
+		message: string;
+	};
+	children?: Record< string, FieldValidity >;
+};
+
+export type DataFormControlProps< Item > = {
+	data: Item;
+	field: NormalizedField< Item >;
+	onChange: ( value: DeepPartial< Item > ) => 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;
+	/**
+	 * Validity information for the field, if any.
+	 */
+	validity?: FieldValidity;
+	/**
+	 * Configuration object for the control.
+	 */
+	config?: {
+		prefix?: React.ComponentType;
+		suffix?: React.ComponentType;
+		rows?: number;
+	};
+};
+
+export type DataViewRenderFieldProps< Item > = {
+	item: Item;
+	field: NormalizedField< Item >;
+	config?: {
+		sizes: string;
+	};
+};

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export type * from './field-api';
+export type * from './dataviews';
+export type * from './dataform';

package/src/{filter-and-sort-data-view.ts → utils/filter-sort-and-paginate.ts}

@@ -35,9 +35,9 @@ import {
 	OPERATOR_NOT_ON,
 	OPERATOR_IN_THE_PAST,
 	OPERATOR_OVER,
-} from './constants';
-import { normalizeFields } from './normalize-fields';
-import type { Field, View } from './types';
+} from '../constants';
+import normalizeFields from './normalize-fields';
+import type { Field, View } from '../types';
 
 function normalizeSearchInput( input = '' ) {
 	return removeAccents( input.trim().toLowerCase() );
@@ -76,7 +76,7 @@ function getRelativeDate( value: number, unit: string ): Date {
  *
  * @return Filtered, sorted and paginated data.
  */
-export function filterSortAndPaginate< Item >(
+export default function filterSortAndPaginate< Item >(
 	data: Item[],
 	view: View,
 	fields: Field< Item >[]

package/src/utils/has-elements.ts

@@ -0,0 +1,11 @@
+/**
+ * Internal dependencies
+ */
+import type { Field } from '../types/field-api';
+
+export default function hasElements< Item >( field: Field< Item > ): boolean {
+	return (
+		( Array.isArray( field.elements ) && field.elements.length > 0 ) ||
+		typeof field.getElements === 'function'
+	);
+}

package/src/{normalize-fields.ts → utils/normalize-fields.ts}

@@ -6,20 +6,21 @@ import type { FunctionComponent } from 'react';
 /**
  * Internal dependencies
  */
-import getFieldTypeDefinition from './field-types';
+import getFieldTypeDefinition from '../field-types';
 import type {
 	DataViewRenderFieldProps,
 	Field,
 	FieldTypeDefinition,
 	NormalizedFilterByConfig,
 	NormalizedField,
-} from './types';
-import { getControl } from './dataform-controls';
+} from '../types';
+import { getControl } from '../dataform-controls';
 import {
 	ALL_OPERATORS,
 	OPERATOR_BETWEEN,
 	SINGLE_SELECTION_OPERATORS,
-} from './constants';
+} from '../constants';
+import hasElements from './has-elements';
 
 const getValueFromId =
 	( id: string ) =>
@@ -37,7 +38,7 @@ const getValueFromId =
 		return value;
 	};
 
-export const setValueFromId =
+const setValueFromId =
 	( id: string ) =>
 	( { value }: { value: any } ) => {
 		const path = id.split( '.' );
@@ -81,7 +82,7 @@ function getFilterBy< Item >(
 		);
 
 		// The `between` operator is not supported when elements are provided.
-		if ( field.elements && operators.includes( OPERATOR_BETWEEN ) ) {
+		if ( hasElements( field ) && operators.includes( OPERATOR_BETWEEN ) ) {
 			operators = operators.filter(
 				( operator ) => operator !== OPERATOR_BETWEEN
 			);
@@ -119,7 +120,10 @@ function getFilterBy< Item >(
 
 	let defaultOperators = fieldTypeDefinition.filterBy.defaultOperators;
 	// The `between` operator is not supported when elements are provided.
-	if ( field.elements && defaultOperators.includes( OPERATOR_BETWEEN ) ) {
+	if (
+		hasElements( field ) &&
+		defaultOperators.includes( OPERATOR_BETWEEN )
+	) {
 		defaultOperators = defaultOperators.filter(
 			( operator ) => operator !== OPERATOR_BETWEEN
 		);
@@ -136,7 +140,7 @@ function getFilterBy< Item >(
  * @param fields Fields config.
  * @return Normalized fields config.
  */
-export function normalizeFields< Item >(
+export default function normalizeFields< Item >(
 	fields: Field< Item >[]
 ): NormalizedField< Item >[] {
 	return fields.map( ( field ) => {
@@ -188,6 +192,7 @@ export function normalizeFields< Item >(
 			sort,
 			isValid,
 			Edit,
+			hasElements: hasElements( field ),
 			enableHiding: field.enableHiding ?? true,
 			enableSorting:
 				field.enableSorting ??