@wordpress/dataviews 11.3.1-next.v.0 → 12.0.0

package/src/hooks/use-form-validity.ts

@@ -40,7 +40,10 @@ function isFormValid( formValidity: FormValidity | undefined ): boolean {
 					// Recursively check children validations
 					return isFormValid( validation as FormValidity );
 				}
-				return validation.type === 'valid';
+				return (
+					validation.type !== 'invalid' &&
+					validation.type !== 'validating'
+				);
 			}
 		);
 	} );
@@ -147,6 +150,7 @@ function setValidityAtPath(
 			current[ segment ] = {};
 		}
 
+		current[ segment ] = { ...current[ segment ] };
 		current = current[ segment ];
 	}
 
@@ -160,6 +164,45 @@ function setValidityAtPath(
 	return result;
 }
 
+function removeValidationProperty(
+	formValidity: FormValidity | undefined,
+	path: string[],
+	property: keyof FieldValidity
+): FormValidity | undefined {
+	if ( ! formValidity || path.length === 0 ) {
+		return formValidity;
+	}
+	const result = { ...formValidity };
+	// Navigate to parent of target.
+	let current: any = result;
+	for ( let i = 0; i < path.length - 1; i++ ) {
+		const segment = path[ i ];
+		if ( ! current[ segment ] ) {
+			return formValidity; // Path doesn't exist
+		}
+		current[ segment ] = { ...current[ segment ] };
+		current = current[ segment ];
+	}
+	const finalKey = path[ path.length - 1 ];
+	if ( ! current[ finalKey ] ) {
+		return formValidity;
+	}
+	const fieldValidity = { ...current[ finalKey ] };
+	delete fieldValidity[ property ];
+	// If field has no more validations, remove it entirely.
+	if ( Object.keys( fieldValidity ).length === 0 ) {
+		delete current[ finalKey ];
+	} else {
+		// Keep the field if it has other validations (including children).
+		current[ finalKey ] = fieldValidity;
+	}
+	// If root is empty, return undefined
+	if ( Object.keys( result ).length === 0 ) {
+		return undefined;
+	}
+	return result;
+}
+
 function handleElementsValidationAsync< Item >(
 	promise: Promise< any >,
 	formField: FormFieldToValidate< Item >,
@@ -215,6 +258,15 @@ function handleElementsValidationAsync< Item >(
 					);
 					return newFormValidity;
 				} );
+			} else {
+				// Validation passed so we need to remove `elements` from validity.
+				setFormValidity( ( prev ) => {
+					return removeValidationProperty(
+						prev,
+						[ ...path, formField.id ],
+						'elements'
+					);
+				} );
 			}
 		} )
 		.catch( ( error ) => {
@@ -265,18 +317,13 @@ function handleCustomValidationAsync< Item >(
 			}
 
 			if ( result === null ) {
+				// Validation passed so we need to remove `custom` from validity.
 				setFormValidity( ( prev ) => {
-					const newFormValidity = setValidityAtPath(
+					return removeValidationProperty(
 						prev,
-						{
-							custom: {
-								type: 'valid',
-								message: __( 'Valid' ),
-							},
-						},
-						[ ...path, formField.id ]
+						[ ...path, formField.id ],
+						'custom'
 					);
-					return newFormValidity;
 				} );
 				return;
 			}
@@ -448,27 +495,6 @@ function validateFormField< Item >(
 		};
 	}
 
-	// Validate the field: isValid.elements (async)
-	if (
-		!! formField.field &&
-		formField.field.isValid.elements &&
-		formField.field.hasElements &&
-		typeof formField.field.getElements === 'function'
-	) {
-		handleElementsValidationAsync(
-			formField.field.getElements(),
-			formField,
-			promiseHandler
-		);
-
-		return {
-			elements: {
-				type: 'validating',
-				message: __( 'Validating…' ),
-			},
-		};
-	}
-
 	// Validate the field: isValid.custom (sync)
 	let customError;
 	if ( !! formField.field && formField.field.isValid.custom ) {
@@ -512,18 +538,41 @@ function validateFormField< Item >(
 		};
 	}
 
+	// Aggregate async validations (`elements` and `custom`).
+	const fieldValidity: FieldValidity = {};
+	// Validate the field: isValid.elements (async)
+	if (
+		!! formField.field &&
+		formField.field.isValid.elements &&
+		formField.field.hasElements &&
+		typeof formField.field.getElements === 'function'
+	) {
+		handleElementsValidationAsync(
+			formField.field.getElements(),
+			formField,
+			promiseHandler
+		);
+		fieldValidity.elements = {
+			type: 'validating',
+			message: __( 'Validating…' ),
+		};
+	}
+
 	// Validate the field: isValid.custom (async)
 	if ( customError instanceof Promise ) {
 		handleCustomValidationAsync( customError, formField, promiseHandler );
 
-		return {
-			custom: {
-				type: 'validating',
-				message: __( 'Validating…' ),
-			},
+		fieldValidity.custom = {
+			type: 'validating',
+			message: __( 'Validating…' ),
 		};
 	}
 
+	// Return aggregated validations if any exist
+	if ( Object.keys( fieldValidity ).length > 0 ) {
+		return fieldValidity;
+	}
+
 	// Validate its children.
 	if ( formField.children.length > 0 ) {
 		const result: Record< string, FieldValidity | undefined > = {};

package/src/hooks/use-report-validity.ts

@@ -0,0 +1,32 @@
+/**
+ * WordPress dependencies
+ */
+import { useEffect } from '@wordpress/element';
+
+/**
+ * Triggers `reportValidity()` on all form inputs within a container element.
+ * This fires the browser's `invalid` event on each input, which validated
+ * controls listen to in order to display their error states.
+ *
+ * Used by panel and card layouts to show validation errors
+ * immediately when their content becomes visible after prior interaction.
+ *
+ * @param ref          A ref to the container element.
+ * @param shouldReport Whether to trigger reportValidity. Typically
+ *                     derived from `touched` state and open/visible state.
+ */
+export default function useReportValidity(
+	ref: React.RefObject< HTMLElement | null >,
+	shouldReport: boolean
+) {
+	useEffect( () => {
+		if ( shouldReport && ref.current ) {
+			const inputs = ref.current.querySelectorAll(
+				'input, textarea, select'
+			);
+			inputs.forEach( ( input ) => {
+				( input as HTMLInputElement ).reportValidity();
+			} );
+		}
+	}, [ shouldReport, ref ] );
+}

package/src/style.scss

@@ -1,5 +1,3 @@
-@use "@wordpress/theme/src/prebuilt/css/design-tokens.css" as *;
-
 @use "./dataviews/style.scss" as *;
 @use "./components/dataviews-bulk-actions/style.scss" as *;
 @use "./components/dataviews-filters/style.scss" as *;

package/src/types/dataform.ts

@@ -21,17 +21,21 @@ export type NormalizedRegularLayout = {
 	labelPosition: LabelPosition;
 };
 
+export type EditVisibility = 'always' | 'on-hover';
+
 export type PanelLayout = {
 	type: 'panel';
 	labelPosition?: LabelPosition;
 	openAs?: 'dropdown' | 'modal';
 	summary?: PanelSummaryField;
+	editVisibility?: EditVisibility;
 };
 export type NormalizedPanelLayout = {
 	type: 'panel';
 	labelPosition: LabelPosition;
 	openAs: 'dropdown' | 'modal';
 	summary: NormalizedPanelSummaryField;
+	editVisibility: EditVisibility;
 };
 
 export type CardSummaryField =
@@ -165,5 +169,6 @@ export interface FieldLayoutProps< Item > {
 	field: NormalizedFormField;
 	onChange: ( value: any ) => void;
 	hideLabelFromVision?: boolean;
+	markWhenOptional?: boolean;
 	validity?: FieldValidity;
 }

package/src/types/field-api.ts

@@ -428,6 +428,10 @@ export type DataFormControlProps< Item > = {
 	field: NormalizedField< Item >;
 	onChange: ( value: DeepPartial< Item > ) => void;
 	hideLabelFromVision?: boolean;
+	/**
+	 * Label the control as "optional" when _not_ required, instead of showing "required".
+	 */
+	markWhenOptional?: boolean;
 	/**
 	 * The currently selected filter operator for this field.
 	 *