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

package/src/dataform-controls/utils/validated-number.tsx

@@ -0,0 +1,171 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	Flex,
+	BaseControl,
+	__experimentalNumberControl as NumberControl,
+	privateApis,
+} from '@wordpress/components';
+import { useCallback } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { OPERATOR_BETWEEN } from '../../constants';
+import type { DataFormControlProps } from '../../types';
+import { unlock } from '../../lock-unlock';
+import getCustomValidity from './get-custom-validity';
+
+const { ValidatedNumberControl } = unlock( privateApis );
+
+type NumberBetween = [ number | string, number | string ];
+
+function toNumberOrEmpty( value?: string ) {
+	if ( value === '' || value === undefined ) {
+		return '';
+	}
+	const number = Number( value );
+	return Number.isFinite( number ) ? number : '';
+}
+
+function BetweenControls( {
+	value,
+	onChange,
+	hideLabelFromVision,
+	step,
+}: {
+	value: NumberBetween;
+	onChange: ( [ min, max ]: NumberBetween ) => void;
+	hideLabelFromVision?: boolean;
+	step: number;
+} ) {
+	const [ min = '', max = '' ] = value;
+
+	const onChangeMin = useCallback(
+		( newValue: string | undefined ) =>
+			onChange( [ toNumberOrEmpty( newValue ), max ] ),
+		[ onChange, max ]
+	);
+
+	const onChangeMax = useCallback(
+		( newValue: string | undefined ) =>
+			onChange( [ min, toNumberOrEmpty( newValue ) ] ),
+		[ onChange, min ]
+	);
+
+	return (
+		<BaseControl
+			__nextHasNoMarginBottom
+			help={ __( 'The max. value must be greater than the min. value.' ) }
+		>
+			<Flex direction="row" gap={ 4 }>
+				<NumberControl
+					label={ __( 'Min.' ) }
+					value={ min }
+					max={ max ? Number( max ) - step : undefined }
+					onChange={ onChangeMin }
+					__next40pxDefaultSize
+					hideLabelFromVision={ hideLabelFromVision }
+					step={ step }
+				/>
+				<NumberControl
+					label={ __( 'Max.' ) }
+					value={ max }
+					min={ min ? Number( min ) + step : undefined }
+					onChange={ onChangeMax }
+					__next40pxDefaultSize
+					hideLabelFromVision={ hideLabelFromVision }
+					step={ step }
+				/>
+			</Flex>
+		</BaseControl>
+	);
+}
+
+export type DataFormValidatedNumberControlProps< Item > =
+	DataFormControlProps< Item > & {
+		/**
+		 * Number of decimals, acceps non-negative integer.
+		 */
+		decimals: number;
+	};
+
+export default function ValidatedNumber< Item >( {
+	data,
+	field,
+	onChange,
+	hideLabelFromVision,
+	operator,
+	decimals,
+	validity,
+}: DataFormValidatedNumberControlProps< Item > ) {
+	const step = Math.pow( 10, Math.abs( decimals ) * -1 );
+	const { label, description, getValue, setValue, isValid } = field;
+	const value = getValue( { item: data } ) ?? '';
+
+	const onChangeControl = useCallback(
+		( newValue: string | undefined ) => {
+			onChange(
+				setValue( {
+					item: data,
+					// Do not convert an empty string or undefined to a number,
+					// otherwise there's a mismatch between the UI control (empty)
+					// and the data relied by onChange (0).
+					value: [ '', undefined ].includes( newValue )
+						? undefined
+						: Number( newValue ),
+				} )
+			);
+		},
+		[ data, onChange, setValue ]
+	);
+
+	const onChangeBetweenControls = useCallback(
+		( newValue: NumberBetween ) => {
+			onChange(
+				setValue( {
+					item: data,
+					value: newValue,
+				} )
+			);
+		},
+		[ data, onChange, setValue ]
+	);
+
+	if ( operator === OPERATOR_BETWEEN ) {
+		let valueBetween: NumberBetween = [ '', '' ];
+		if (
+			Array.isArray( value ) &&
+			value.length === 2 &&
+			value.every(
+				( element ) => typeof element === 'number' || element === ''
+			)
+		) {
+			valueBetween = value as NumberBetween;
+		}
+		return (
+			<BetweenControls
+				value={ valueBetween }
+				onChange={ onChangeBetweenControls }
+				hideLabelFromVision={ hideLabelFromVision }
+				step={ step }
+			/>
+		);
+	}
+
+	return (
+		<ValidatedNumberControl
+			required={ !! isValid?.required }
+			customValidity={ getCustomValidity( isValid, validity ) }
+			label={ label }
+			help={ description }
+			value={ value }
+			onChange={ onChangeControl }
+			__next40pxDefaultSize
+			hideLabelFromVision={ hideLabelFromVision }
+			step={ step }
+		/>
+	);
+}

package/src/{dataforms-layouts → dataform-layouts}/card/index.tsx

@@ -10,10 +10,18 @@ import { chevronDown, chevronUp } from '@wordpress/icons';
  */
 import { getFormFieldLayout } from '..';
 import DataFormContext from '../../components/dataform-context';
-import type { NormalizedCardLayout, FieldLayoutProps, Form } from '../../types';
+import type {
+	NormalizedCardLayout,
+	CardLayout,
+	FieldLayoutProps,
+	Form,
+	Layout,
+	NormalizedField,
+} from '../../types';
 import { DataFormLayout } from '../data-form-layout';
 import { isCombinedField } from '../is-combined-field';
-import { DEFAULT_LAYOUT, normalizeLayout } from '../../normalize-form-fields';
+import { DEFAULT_LAYOUT, normalizeLayout } from '../normalize-form-fields';
+import { getSummaryFields } from '../get-summary-fields';
 
 export function useCollapsibleCard( initialIsOpen: boolean = true ) {
 	const [ isOpen, setIsOpen ] = useState( initialIsOpen );
@@ -63,22 +71,74 @@ export function useCollapsibleCard( initialIsOpen: boolean = true ) {
 	return { isOpen, CollapsibleCardHeader };
 }
 
+function isSummaryFieldVisible< Item >(
+	summaryField: NormalizedField< Item >,
+	summaryConfig: NormalizedCardLayout[ 'summary' ],
+	isOpen: boolean
+) {
+	// If no summary config, dont't show any fields
+	if (
+		! summaryConfig ||
+		( Array.isArray( summaryConfig ) && summaryConfig.length === 0 )
+	) {
+		return false;
+	}
+
+	// Convert to array for consistent handling
+	const summaryConfigArray = Array.isArray( summaryConfig )
+		? summaryConfig
+		: [ summaryConfig ];
+
+	// Find the config for this specific field
+	const fieldConfig = summaryConfigArray.find( ( config ) => {
+		if ( typeof config === 'string' ) {
+			return config === summaryField.id;
+		}
+		if ( typeof config === 'object' && 'id' in config ) {
+			return config.id === summaryField.id;
+		}
+		return false;
+	} );
+
+	// If field is not in summary config, don't show it
+	if ( ! fieldConfig ) {
+		return false;
+	}
+
+	// If it's a string, always show it
+	if ( typeof fieldConfig === 'string' ) {
+		return true;
+	}
+
+	// If it has visibility rules, respect them
+	if ( typeof fieldConfig === 'object' && 'visibility' in fieldConfig ) {
+		return (
+			fieldConfig.visibility === 'always' ||
+			( fieldConfig.visibility === 'when-collapsed' && ! isOpen )
+		);
+	}
+
+	// Default to always show
+	return true;
+}
+
 export default function FormCardField< Item >( {
 	data,
 	field,
 	onChange,
 	hideLabelFromVision,
+	validity,
 }: FieldLayoutProps< Item > ) {
 	const { fields } = useContext( DataFormContext );
 
 	const layout: NormalizedCardLayout = normalizeLayout( {
 		...field.layout,
 		type: 'card',
-	} ) as NormalizedCardLayout;
+	} as CardLayout ) as NormalizedCardLayout;
 
 	const form: Form = useMemo(
 		(): Form => ( {
-			layout: DEFAULT_LAYOUT,
+			layout: DEFAULT_LAYOUT as Layout,
 			fields: isCombinedField( field ) ? field.children : [],
 		} ),
 		[ field ]
@@ -87,13 +147,36 @@ export default function FormCardField< Item >( {
 	const { isOpen, CollapsibleCardHeader } = useCollapsibleCard(
 		layout.isOpened
 	);
+
+	const summaryFields = getSummaryFields< Item >( layout.summary, fields );
+
+	const visibleSummaryFields = summaryFields.filter( ( summaryField ) =>
+		isSummaryFieldVisible( summaryField, layout.summary, isOpen )
+	);
+
 	if ( isCombinedField( field ) ) {
 		const withHeader = !! field.label && layout.withHeader;
 		return (
 			<Card className="dataforms-layouts-card__field">
 				{ withHeader && (
-					<CollapsibleCardHeader className="dataforms-layouts-card__field-label">
-						{ field.label }
+					<CollapsibleCardHeader className="dataforms-layouts-card__field-header">
+						<span className="dataforms-layouts-card__field-header-label">
+							{ field.label }
+						</span>
+						{ visibleSummaryFields.length > 0 &&
+							layout.withHeader && (
+								<div className="dataforms-layouts-card__field-summary">
+									{ visibleSummaryFields.map(
+										( summaryField ) => (
+											<summaryField.render
+												key={ summaryField.id }
+												item={ data }
+												field={ summaryField }
+											/>
+										)
+									) }
+								</div>
+							) }
 					</CollapsibleCardHeader>
 				) }
 				{ ( isOpen || ! withHeader ) && (
@@ -109,6 +192,7 @@ export default function FormCardField< Item >( {
 							data={ data }
 							form={ form }
 							onChange={ onChange }
+							validity={ validity?.children }
 						/>
 					</CardBody>
 				) }
@@ -132,8 +216,21 @@ export default function FormCardField< Item >( {
 	return (
 		<Card className="dataforms-layouts-card__field">
 			{ withHeader && (
-				<CollapsibleCardHeader className="dataforms-layouts-card__field-label">
-					{ fieldDefinition.label }
+				<CollapsibleCardHeader className="dataforms-layouts-card__field-header">
+					<span className="dataforms-layouts-card__field-header-label">
+						{ fieldDefinition.label }
+					</span>
+					{ visibleSummaryFields.length > 0 && layout.withHeader && (
+						<div className="dataforms-layouts-card__field-summary">
+							{ visibleSummaryFields.map( ( summaryField ) => (
+								<summaryField.render
+									key={ summaryField.id }
+									item={ data }
+									field={ summaryField }
+								/>
+							) ) }
+						</div>
+					) }
 				</CollapsibleCardHeader>
 			) }
 			{ ( isOpen || ! withHeader ) && (
@@ -147,6 +244,7 @@ export default function FormCardField< Item >( {
 						hideLabelFromVision={
 							hideLabelFromVision || withHeader
 						}
+						validity={ validity }
 					/>
 				</CardBody>
 			) }

package/src/dataform-layouts/card/style.scss

@@ -0,0 +1,24 @@
+@use "@wordpress/base-styles/colors" as *;
+@use "@wordpress/base-styles/variables" as *;
+@use "@wordpress/base-styles/mixins" as *;
+
+.dataforms-layouts-card__field-header-label {
+	@include heading-large();
+}
+
+.dataforms-layouts-card__field {
+	width: 100%;
+}
+
+.dataforms-layouts-card__field-description {
+	color: $gray-700;
+	display: block;
+	font-size: $font-size-medium;
+	margin-bottom: $grid-unit-20;
+}
+
+.dataforms-layouts-card__field-summary {
+	display: flex;
+	flex-direction: row;
+	gap: $grid-unit-20;
+}

package/src/{dataforms-layouts → dataform-layouts}/data-form-layout.tsx

@@ -7,34 +7,46 @@ import { useContext, useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import type { Form, FormField, SimpleFormField } from '../types';
+import type {
+	FieldValidity,
+	Form,
+	FormField,
+	FormValidity,
+	SimpleFormField,
+} from '../types';
 import { getFormFieldLayout } from './index';
 import DataFormContext from '../components/dataform-context';
 import { isCombinedField } from './is-combined-field';
-import normalizeFormFields, { normalizeLayout } from '../normalize-form-fields';
+import normalizeFormFields, { normalizeLayout } from './normalize-form-fields';
 
 const DEFAULT_WRAPPER = ( { children }: { children: React.ReactNode } ) => (
-	<VStack spacing={ 4 }>{ children }</VStack>
+	<VStack className="dataforms-layouts__wrapper" spacing={ 4 }>
+		{ children }
+	</VStack>
 );
 
 export function DataFormLayout< Item >( {
 	data,
 	form,
 	onChange,
+	validity,
 	children,
 	as,
 }: {
 	data: Item;
 	form: Form;
 	onChange: ( value: any ) => void;
+	validity?: FormValidity;
 	children?: (
 		FieldLayout: ( props: {
 			data: Item;
 			field: FormField;
 			onChange: ( value: any ) => void;
 			hideLabelFromVision?: boolean;
+			validity?: FieldValidity;
 		} ) => React.JSX.Element | null,
-		field: FormField
+		childField: FormField,
+		childFieldValidity?: FieldValidity
 	) => React.JSX.Element;
 	as?: React.ComponentType< { children: React.ReactNode } >;
 } ) {
@@ -82,7 +94,11 @@ export function DataFormLayout< Item >( {
 				}
 
 				if ( children ) {
-					return children( FieldLayout, formField );
+					return children(
+						FieldLayout,
+						formField,
+						validity?.[ formField.id ]
+					);
 				}
 
 				return (
@@ -91,6 +107,7 @@ export function DataFormLayout< Item >( {
 						data={ data }
 						field={ formField }
 						onChange={ onChange }
+						validity={ validity?.[ formField.id ] }
 					/>
 				);
 			} ) }

package/src/dataform-layouts/get-summary-fields.ts

@@ -0,0 +1,42 @@
+/**
+ * Internal dependencies
+ */
+import type { NormalizedField, NormalizedSummaryField } from '../types';
+
+/**
+ * Extracts field IDs from various summary field formats.
+ *
+ * @param summary The summary field configuration.
+ * @return Array of field IDs.
+ */
+function extractSummaryIds( summary: NormalizedSummaryField ): string[] {
+	if ( Array.isArray( summary ) ) {
+		return summary.map( ( item ) =>
+			typeof item === 'string' ? item : item.id
+		);
+	}
+
+	return [];
+}
+
+/**
+ * Returns the summary fields for a given field.
+ * @param summaryField - The summary field configuration.
+ * @param fields       - The fields to get the summary fields from.
+ * @return The summary fields.
+ */
+export const getSummaryFields = < Item >(
+	summaryField: NormalizedSummaryField,
+	fields: NormalizedField< Item >[]
+): NormalizedField< Item >[] => {
+	if ( Array.isArray( summaryField ) && summaryField.length > 0 ) {
+		const summaryIds = extractSummaryIds( summaryField );
+		return summaryIds
+			.map( ( summaryId ) =>
+				fields.find( ( _field ) => _field.id === summaryId )
+			)
+			.filter( ( _field ) => _field !== undefined );
+	}
+
+	return [];
+};

package/src/{dataforms-layouts → dataform-layouts}/index.tsx

@@ -19,17 +19,47 @@ const FORM_FIELD_LAYOUTS = [
 	{
 		type: 'regular',
 		component: FormRegularField,
+		wrapper: ( {
+			children,
+			layout,
+		}: {
+			children: React.ReactNode;
+			layout: Layout;
+		} ) => (
+			<VStack
+				className="dataforms-layouts__wrapper"
+				spacing={ ( layout as any )?.spacing ?? 4 }
+			>
+				{ children }
+			</VStack>
+		),
 	},
 	{
 		type: 'panel',
 		component: FormPanelField,
 		wrapper: ( { children }: { children: React.ReactNode } ) => (
-			<VStack spacing={ 2 }>{ children }</VStack>
+			<VStack className="dataforms-layouts__wrapper" spacing={ 2 }>
+				{ children }
+			</VStack>
 		),
 	},
 	{
 		type: 'card',
 		component: FormCardField,
+		wrapper: ( {
+			children,
+			layout,
+		}: {
+			children: React.ReactNode;
+			layout: Layout;
+		} ) => (
+			<VStack
+				className="dataforms-layouts__wrapper"
+				spacing={ ( layout as any )?.spacing ?? 6 }
+			>
+				{ children }
+			</VStack>
+		),
 	},
 	{
 		type: 'row',
@@ -41,7 +71,7 @@ const FORM_FIELD_LAYOUTS = [
 			children: React.ReactNode;
 			layout: Layout;
 		} ) => (
-			<VStack spacing={ 4 }>
+			<VStack className="dataforms-layouts__wrapper" spacing={ 4 }>
 				<div className="dataforms-layouts-row__field">
 					<HStack
 						spacing={ 4 }

package/src/{normalize-form-fields.ts → dataform-layouts/normalize-form-fields.ts}

@@ -9,7 +9,9 @@ import type {
 	NormalizedPanelLayout,
 	NormalizedCardLayout,
 	NormalizedRowLayout,
-} from './types';
+	NormalizedCardSummaryField,
+	CardSummaryField,
+} from '../types';
 
 interface NormalizedFormField {
 	id: string;
@@ -21,6 +23,20 @@ export const DEFAULT_LAYOUT: NormalizedLayout = {
 	labelPosition: 'top',
 };
 
+const normalizeCardSummaryField = (
+	sum: CardSummaryField
+): NormalizedCardSummaryField => {
+	if ( typeof sum === 'string' ) {
+		return [ { id: sum, visibility: 'when-collapsed' } ];
+	}
+	return sum.map( ( item ) => {
+		if ( typeof item === 'string' ) {
+			return { id: item, visibility: 'when-collapsed' };
+		}
+		return { id: item.id, visibility: item.visibility };
+	} );
+};
+
 /**
  * Normalizes a layout configuration based on its type.
  *
@@ -36,10 +52,16 @@ export function normalizeLayout( layout?: Layout ): NormalizedLayout {
 			labelPosition: layout?.labelPosition ?? 'top',
 		} satisfies NormalizedRegularLayout;
 	} else if ( layout?.type === 'panel' ) {
+		const summary = layout.summary ?? [];
+		const normalizedSummary = Array.isArray( summary )
+			? summary
+			: [ summary ];
+
 		normalizedLayout = {
 			type: 'panel',
 			labelPosition: layout?.labelPosition ?? 'side',
 			openAs: layout?.openAs ?? 'dropdown',
+			summary: normalizedSummary,
 		} satisfies NormalizedPanelLayout;
 	} else if ( layout?.type === 'card' ) {
 		if ( layout.withHeader === false ) {
@@ -49,8 +71,11 @@ export function normalizeLayout( layout?: Layout ): NormalizedLayout {
 				type: 'card',
 				withHeader: false,
 				isOpened: true,
+				summary: [],
 			} satisfies NormalizedCardLayout;
 		} else {
+			const summary = layout.summary ?? [];
+
 			normalizedLayout = {
 				type: 'card',
 				withHeader: true,
@@ -58,12 +83,14 @@ export function normalizeLayout( layout?: Layout ): NormalizedLayout {
 					typeof layout.isOpened === 'boolean'
 						? layout.isOpened
 						: true,
+				summary: normalizeCardSummaryField( summary ),
 			} satisfies NormalizedCardLayout;
 		}
 	} else if ( layout?.type === 'row' ) {
 		normalizedLayout = {
 			type: 'row',
 			alignment: layout?.alignment ?? 'center',
+			styles: layout?.styles ?? {},
 		} satisfies NormalizedRowLayout;
 	}