DataForm - Card Layout: implement summary field

packages/dataviews/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Breaking changes
+
+- DataForm: Add summary field support for both card and panel layouts. The `summary` property has been moved from the field level to the layout level, and so fields using `summary` at the field level must now configure it within the `layout` object. Additionally, the first children will only be used as summary for the panel if 1) there is no `layout.summary` and 2) the form field ID doesn't match any existing field. See README for details. [#71576](https://github.com/WordPress/gutenberg/pull/71576)
+
 ## 9.1.0 (2025-10-01)
 
 ### Features

packages/dataviews/README.md

@@ -643,7 +643,7 @@ Example:
 const form = {
 	layout: {
 		type: 'panel',
-		labelPosition: 'side'
+		labelPosition: 'side',
 	},
 	fields: [
 		'title',
@@ -1235,9 +1235,9 @@ Example:
 
 Object that contains the validation rules for the field. If a rule is not met, the control will be marked as invalid and a message will be displayed.
 
-- `required`: boolean indicating whether the field is required or not.
-- `elements`: boolean restricting selection to the provided list of elements only. Used with the `array` field type.
-- `custom`: a function that validates a field's value. If the value is invalid, the function should return a string explaining why the value is invalid. Otherwise, the function must return null.
+-   `required`: boolean indicating whether the field is required or not.
+-   `elements`: boolean restricting selection to the provided list of elements only. Used with the `array` field type.
+-   `custom`: a function that validates a field's value. If the value is invalid, the function should return a string explaining why the value is invalid. Otherwise, the function must return null.
 
 Example:
 
@@ -1280,9 +1280,9 @@ Fields that define their own Edit component have access to the validation rules
 
 ```js
 {
-  Edit: ( { field }) => {
-	  return <input required={ !! field.isValid.required } />
-  }
+	Edit: ( { field } ) => {
+		return <input required={ !! field.isValid.required } />;
+	};
 }
 ```
 
@@ -1409,8 +1409,8 @@ Operators:
 | `contains`           | Text           | `CONTAINS`. The item's field contains the given substring.                                           | Title contains: Mars                               |
 | `notContains`        | Text           | `NOT CONTAINS`. The item's field does not contain the given substring.                               | Description doesn't contain: photo                 |
 | `startsWith`         | Text           | `STARTS WITH`. The item's field starts with the given substring.                                     | Title starts with: Mar                             |
-| `on`                 | Date           | `ON`. The item's field is on a given date (date equality using proper date parsing).                | Date is on: 2024-01-01                             |
-| `notOn`              | Date           | `NOT ON`. The item's field is not on a given date (date inequality using proper date parsing).      | Date is not on: 2024-01-01                         |
+| `on`                 | Date           | `ON`. The item's field is on a given date (date equality using proper date parsing).                 | Date is on: 2024-01-01                             |
+| `notOn`              | Date           | `NOT ON`. The item's field is not on a given date (date inequality using proper date parsing).       | Date is not on: 2024-01-01                         |
 | `before`             | Date           | `BEFORE`. The item's field is before a given date.                                                   | Date is before 2024-01-01                          |
 | `after`              | Date           | `AFTER`. The item's field is after a given date.                                                     | Date is after 2024-01-01                           |
 | `beforeInc`          | Date           | `BEFORE (Inc)`. The item's field is before a given date, including the date.                         | Date is before 2024-01-01, including 2024-01-01    |
@@ -1480,8 +1480,8 @@ Represents the type of layout used to render the field. It'll be one of Regular,
 
 #### Regular
 
-- `type`: `regular`. Required.
-- `labelPosition`: one of `side`, `top`, or `none`. Optional. `top` by default.
+-   `type`: `regular`. Required.
+-   `labelPosition`: one of `side`, `top`, or `none`. Optional. `top` by default.
 
 For example:
 
@@ -1499,6 +1499,16 @@ For example:
 
 - `type`: `panel`. Required.
 - `labelPosition`: one of `side`, `top`, or `none`. Optional. `top` by default.
+- `summary`: Summary field configuration. Optional. Specifies which field(s) to display in the panel header. Can be:
+   	- A string (single field ID)
+    - An array of strings (multiple field IDs)
+
+When no summary fields are explicitly configured, the panel automatically determines which fields to display using this priority:
+
+1. Use `summary` fields if they exist
+2. Fall back to the field definition that matches the form field's id
+3. If the form field id doesn't exist, pick the first child field
+4. If no field definition is found, return empty summary fields
 
 For example:
 ```js
@@ -1513,9 +1523,18 @@ For example:
 
 #### Card
 
-- `type`: `card`. Required.
-- `isOpened`: boolean. Optional. `true` by default.
-- `withHeader`: boolean. Optional. `true` by default.
+-   `type`: `card`. Required.
+-   `isOpened`: boolean. Optional. `true` by default.
+-   `withHeader`: boolean. Optional. `true` by default.
+-   `summary`: Summary field configuration. Optional. Specifies which field(s) to display in the card header. Can be:
+    -   A string (single field ID)
+    -   An array of strings (multiple field IDs)
+    -   An array of objects for per-field visibility control `[{ id: string, visibility: 'always' | 'when-collapsed' }]`
+
+Cards can be collapsed while visible, so you can control when summary fields appear:
+
+-   `'always'`: Show the field in both expanded and collapsed states.
+-   `'when-collapsed'`: Show the field only when the card is collapsed. This is the default.
 
 For example:
 
@@ -1532,8 +1551,8 @@ For example:
 
 #### Row
 
-- `type`: `row`. Required.
-- `alignment`: one of `start`, `center`, or `end`. Optional. `center` by default.
+-   `type`: `row`. Required.
+-   `alignment`: one of `start`, `center`, or `end`. Optional. `center` by default.
 
 The Row layout displays fields horizontally in a single row. It's particularly useful for grouping related fields that should be displayed side by side. This layout can be used both as a top-level form layout and for individual field groups.
 
@@ -1576,7 +1595,9 @@ Example:
 ```js
 {
 	id: 'status',
-	layout: 'panel',
+	layout: {
+		type: 'panel',
+	},
 	label: 'Combined Field',
 	children: [ 'field1', 'field2' ],
 }

packages/dataviews/src/components/dataform/stories/index.story.tsx

@@ -29,7 +29,7 @@ import type {
 } from '../../../types';
 import { unlock } from '../../../lock-unlock';
 
-const { ValidatedTextControl } = unlock( privateApis );
+const { ValidatedTextControl, Badge } = unlock( privateApis );
 
 type SamplePost = {
 	title: string;
@@ -431,7 +431,6 @@ const LayoutPanelComponent = ( {
 					id: 'discussion',
 					label: 'Discussion',
 					children: [ 'comment_status', 'ping_status' ],
-					summary: 'discussion',
 				},
 				{
 					id: 'address1',
@@ -447,13 +446,19 @@ const LayoutPanelComponent = ( {
 						'flight_status',
 						'gate',
 					],
-					summary: [ 'origin', 'destination', 'flight_status' ],
+					layout: {
+						type: 'panel',
+						summary: [ 'origin', 'destination', 'flight_status' ],
+					},
 				},
 				{
 					id: 'passenger_details',
 					label: 'Passenger Details',
 					children: [ 'author', 'seat' ],
-					summary: [ 'author', 'seat' ],
+					layout: {
+						type: 'panel',
+						summary: [ 'author', 'seat' ],
+					},
 				},
 			],
 		};
@@ -999,6 +1004,7 @@ const LayoutCardComponent = ( { withHeader }: { withHeader: boolean } ) => {
 		hasVat: boolean;
 		vat: number;
 		commission: number;
+		dueDate: string;
 	};
 
 	const customerFields: Field< Customer >[] = [
@@ -1070,6 +1076,22 @@ const LayoutCardComponent = ( { withHeader }: { withHeader: boolean } ) => {
 			label: 'Commission',
 			type: 'integer',
 		},
+		{
+			id: 'dueDate',
+			label: 'Due Date',
+			type: 'text',
+			render: ( { item } ) => {
+				return <Badge>Due on: { item.dueDate }</Badge>;
+			},
+		},
+		{
+			id: 'plan-summary',
+			type: 'text',
+			readOnly: true,
+			render: ( { item } ) => {
+				return <Badge>{ item.plan }</Badge>;
+			},
+		},
 	];
 
 	const [ customer, setCustomer ] = useState< Customer >( {
@@ -1086,6 +1108,7 @@ const LayoutCardComponent = ( { withHeader }: { withHeader: boolean } ) => {
 		hasVat: true,
 		vat: 10,
 		commission: 5,
+		dueDate: 'March 1st, 2028',
 	} );
 
 	const form: Form = useMemo(
@@ -1097,14 +1120,18 @@ const LayoutCardComponent = ( { withHeader }: { withHeader: boolean } ) => {
 			fields: [
 				{
 					id: 'customerCard',
+					layout: { type: 'card', summary: 'plan-summary' },
 					label: 'Customer',
 					description:
 						'Enter your contact details, plan type, and addresses to complete your customer information.',
 					children: [
 						{
 							id: 'customerContact',
 							label: 'Contact',
-							layout: { type: 'panel', labelPosition: 'top' },
+							layout: {
+								type: 'panel',
+								labelPosition: 'top',
+							},
 							children: [
 								{
 									id: 'name',
@@ -1157,6 +1184,7 @@ const LayoutCardComponent = ( { withHeader }: { withHeader: boolean } ) => {
 					layout: {
 						type: 'card',
 						isOpened: false,
+						summary: [ { id: 'dueDate', visibility: 'always' } ],
 					},
 					children: [ 'vat', 'commission' ],
 				},

packages/dataviews/src/dataforms-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 { getSummaryFields } from '../get-summary-fields';
 
 export function useCollapsibleCard( initialIsOpen: boolean = true ) {
 	const [ isOpen, setIsOpen ] = useState( initialIsOpen );
@@ -63,6 +71,57 @@ 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,
@@ -74,11 +133,11 @@ export default function FormCardField< Item >( {
 	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 +146,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 ) && (
@@ -132,8 +214,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 ) && (

packages/dataviews/src/dataforms-layouts/card/style.scss

@@ -8,3 +8,9 @@
 	font-size: $font-size-medium;
 	margin-bottom: $grid-unit-20;
 }
+
+.dataforms-layouts-card__field-summary {
+	display: flex;
+	flex-direction: row;
+	gap: $grid-unit-20;
+}