@wordpress/dataviews 4.0.0 → 4.2.0

package/src/types.ts

@@ -42,9 +42,31 @@ export type Operator =
 	| 'isAll'
 	| 'isNotAll';
 
-export type ItemRecord = Record< string, unknown >;
+export type FieldType = 'text' | 'integer' | 'datetime';
 
-export type FieldType = 'text';
+export type ValidationContext = {
+	elements?: Option[];
+};
+
+/**
+ * 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: ( item: Item, context?: ValidationContext ) => boolean;
+
+	/**
+	 * Callback used to render an edit control for the field or control name.
+	 */
+	Edit: ComponentType< DataFormControlProps< Item > > | string;
+};
 
 /**
  * A dataview field for a specific property of a data type.
@@ -65,6 +87,17 @@ export type Field< Item > = {
 	 */
 	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.
 	 */
@@ -75,6 +108,21 @@ export type Field< Item > = {
 	 */
 	render?: ComponentType< { item: Item } >;
 
+	/**
+	 * Callback used to render an edit control for the field.
+	 */
+	Edit?: ComponentType< DataFormControlProps< Item > > | string;
+
+	/**
+	 * Callback used to sort the field.
+	 */
+	sort?: ( a: Item, b: Item, direction: SortDirection ) => number;
+
+	/**
+	 * Callback used to validate the field.
+	 */
+	isValid?: ( item: Item, context?: ValidationContext ) => boolean;
+
 	/**
 	 * Whether the field is sortable.
 	 */
@@ -99,26 +147,22 @@ export type Field< Item > = {
 	 * Filter config for the field.
 	 */
 	filterBy?: FilterByConfig | undefined;
-} & ( Item extends ItemRecord
-	? {
-			/**
-			 * 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 retrieve the value of the field from the item.
-			 * Defaults to `item[ field.id ]`.
-			 */
-			getValue: ( args: { item: Item } ) => any;
-	  } );
+
+	/**
+	 * Callback used to retrieve the value of the field from the item.
+	 * Defaults to `item[ field.id ]`.
+	 */
+	getValue?: ( args: { item: Item } ) => any;
+};
 
 export type NormalizedField< Item > = Field< Item > & {
 	label: string;
+	header: string | ReactElement;
 	getValue: ( args: { item: Item } ) => any;
 	render: ComponentType< { item: Item } >;
+	Edit: ComponentType< DataFormControlProps< Item > >;
+	sort: ( a: Item, b: Item, direction: SortDirection ) => number;
+	isValid: ( item: Item, context?: ValidationContext ) => boolean;
 };
 
 /**
@@ -132,7 +176,15 @@ export type Data< Item > = Item[];
  * The form configuration.
  */
 export type Form = {
-	visibleFields?: string[];
+	type?: 'regular' | 'panel';
+	fields?: string[];
+};
+
+export type DataFormControlProps< Item > = {
+	data: Item;
+	field: NormalizedField< Item >;
+	onChange: ( value: Record< string, any > ) => void;
+	hideLabelFromVision?: boolean;
 };
 
 /**
@@ -244,6 +296,8 @@ export interface CombinedField {
 
 	label: string;
 
+	header?: string | ReactElement;
+
 	/**
 	 * The fields to use as columns.
 	 */
@@ -381,6 +435,18 @@ interface ActionBase< Item > {
 	 * Whether the action can be used as a bulk action.
 	 */
 	supportsBulk?: boolean;
+
+	/**
+	 * The context in which the action is visible.
+	 * This is only a "meta" information for now.
+	 */
+	context?: 'list' | 'single';
+}
+
+export interface RenderModalProps< Item > {
+	items: Item[];
+	closeModal?: () => void;
+	onActionPerformed?: ( items: Item[] ) => void;
 }
 
 export interface ActionModal< Item > extends ActionBase< Item > {
@@ -391,11 +457,7 @@ export interface ActionModal< Item > extends ActionBase< Item > {
 		items,
 		closeModal,
 		onActionPerformed,
-	}: {
-		items: Item[];
-		closeModal?: () => void;
-		onActionPerformed?: ( items: Item[] ) => void;
-	} ) => ReactElement;
+	}: RenderModalProps< Item > ) => ReactElement;
 
 	/**
 	 * Whether to hide the modal header.
@@ -459,3 +521,10 @@ export interface SupportedLayouts {
 	grid?: Omit< ViewGrid, 'type' >;
 	table?: Omit< ViewTable, 'type' >;
 }
+
+export interface DataFormProps< Item > {
+	data: Item;
+	fields: Field< Item >[];
+	form: Form;
+	onChange: ( value: Record< string, any > ) => void;
+}

package/src/validation.ts

@@ -0,0 +1,18 @@
+/**
+ * Internal dependencies
+ */
+import { normalizeFields } from './normalize-fields';
+import type { Field, Form } from './types';
+
+export function isItemValid< Item >(
+	item: Item,
+	fields: Field< Item >[],
+	form: Form
+): boolean {
+	const _fields = normalizeFields(
+		fields.filter( ( { id } ) => !! form.fields?.includes( id ) )
+	);
+	return _fields.every( ( field ) => {
+		return field.isValid( item, { elements: field.elements } );
+	} );
+}

package/tsconfig.json

@@ -14,7 +14,8 @@
 		{ "path": "../i18n" },
 		{ "path": "../icons" },
 		{ "path": "../primitives" },
-		{ "path": "../private-apis" }
+		{ "path": "../private-apis" },
+		{ "path": "../warning" }
 	],
 	"include": [ "src" ]
 }