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

package/src/dataform/stories/content.story.tsx

@@ -0,0 +1,390 @@
+/**
+ * WordPress dependencies
+ */
+import { useMemo, useState, useRef, useEffect } from '@wordpress/element';
+import { Stack } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import DataForm from '../index';
+import useFormValidity from '../../hooks/use-form-validity';
+import type { Field, Form } from '../../types';
+
+const meta: Meta< typeof DataForm > = {
+	title: 'DataViews/DataForm/Content',
+	component: DataForm,
+	parameters: {
+		controls: { disable: true },
+	},
+	tags: [ '!dev' /* Hide individual story pages from sidebar */ ],
+};
+export default meta;
+
+type Story = StoryObj< typeof DataForm >;
+
+type SampleData = {
+	name: string;
+	email: string;
+	phone: string;
+};
+
+export const Labels: Story = {
+	render: () => {
+		const [ data, setData ] = useState< SampleData >( {
+			name: '',
+			email: '',
+			phone: '',
+		} );
+
+		const fields: Field< SampleData >[] = useMemo(
+			() => [
+				{
+					id: 'name',
+					label: 'Name',
+					type: 'text',
+				},
+				{
+					id: 'email',
+					label: 'Email',
+					type: 'email',
+				},
+				{
+					id: 'phone',
+					label: 'Phone number',
+					type: 'telephone',
+				},
+			],
+			[]
+		);
+
+		const form: Form = useMemo(
+			() => ( {
+				layout: { type: 'regular' },
+				fields: [ 'name', 'email', 'phone' ],
+			} ),
+			[]
+		);
+
+		return (
+			<Stack direction="column" gap="lg">
+				<DataForm< SampleData >
+					data={ data }
+					fields={ fields }
+					form={ form }
+					onChange={ ( edits ) =>
+						setData( ( prev ) => ( { ...prev, ...edits } ) )
+					}
+				/>
+			</Stack>
+		);
+	},
+};
+
+type HelpTextData = {
+	name: string;
+	email: string;
+	phone: string;
+};
+
+export const HelpText: Story = {
+	render: () => {
+		const [ data, setData ] = useState< HelpTextData >( {
+			name: '',
+			email: '',
+			phone: '',
+		} );
+
+		const fields: Field< HelpTextData >[] = useMemo(
+			() => [
+				{
+					id: 'name',
+					label: 'Name',
+					type: 'text',
+					placeholder: 'Jane Doe',
+					description:
+						'Enter your full legal name as it appears on official documents.',
+				},
+				{
+					id: 'email',
+					label: 'Email',
+					type: 'email',
+					placeholder: 'you@example.com',
+					description:
+						'We will use this to send you important account notifications and updates.',
+				},
+				{
+					id: 'phone',
+					label: 'Phone number',
+					type: 'telephone',
+					placeholder: '+1 (555) 123-4567',
+					description:
+						'Include your country code. This number will be used for account verification.',
+				},
+			],
+			[]
+		);
+
+		const form: Form = useMemo(
+			() => ( {
+				layout: { type: 'regular' },
+				fields: [ 'name', 'email', 'phone' ],
+			} ),
+			[]
+		);
+
+		return (
+			<Stack direction="column" gap="lg">
+				<DataForm< HelpTextData >
+					data={ data }
+					fields={ fields }
+					form={ form }
+					onChange={ ( edits ) =>
+						setData( ( prev ) => ( { ...prev, ...edits } ) )
+					}
+				/>
+			</Stack>
+		);
+	},
+};
+
+type ValidationMessagesData = {
+	name: string;
+	email: string;
+	phone: string;
+};
+
+export const ValidationMessages: Story = {
+	render: () => {
+		const [ data, setData ] = useState< ValidationMessagesData >( {
+			name: '',
+			email: 'invalid-email',
+			phone: '123',
+		} );
+
+		const fields: Field< ValidationMessagesData >[] = useMemo(
+			() => [
+				{
+					id: 'name',
+					label: 'Name',
+					type: 'text',
+					placeholder: 'Jane Doe',
+					isValid: {
+						required: true,
+					},
+				},
+				{
+					id: 'email',
+					label: 'Email',
+					type: 'email',
+					placeholder: 'you@example.com',
+					isValid: {
+						required: true,
+						custom: ( item ) => {
+							if ( ! item.email ) {
+								return null;
+							}
+							if ( ! item.email.includes( '@' ) ) {
+								return 'Please enter a valid email address.';
+							}
+							return null;
+						},
+					},
+				},
+				{
+					id: 'phone',
+					label: 'Phone number',
+					type: 'telephone',
+					placeholder: '+1 (555) 123-4567',
+					isValid: {
+						required: true,
+						custom: ( item ) => {
+							if ( ! item.phone ) {
+								return null;
+							}
+							if ( item.phone.length < 10 ) {
+								return 'Phone number must be at least 10 digits long.';
+							}
+							return null;
+						},
+					},
+				},
+			],
+			[]
+		);
+
+		const form: Form = useMemo(
+			() => ( {
+				layout: { type: 'regular' },
+				fields: [ 'name', 'email', 'phone' ],
+			} ),
+			[]
+		);
+
+		const { validity } = useFormValidity( data, fields, form );
+		const containerRef = useRef< HTMLDivElement >( null );
+
+		// Show validation messages on load without focusing
+		useEffect( () => {
+			if ( validity && containerRef.current ) {
+				const inputs = containerRef.current.querySelectorAll( 'input' );
+				inputs.forEach( ( input ) => {
+					// Dispatch 'invalid' event to trigger the validation message display
+					input.dispatchEvent(
+						new Event( 'invalid', { bubbles: false } )
+					);
+				} );
+			}
+		}, [ validity ] );
+
+		return (
+			<div ref={ containerRef }>
+				<Stack direction="column" gap="xl">
+					<DataForm< ValidationMessagesData >
+						data={ data }
+						fields={ fields }
+						form={ form }
+						validity={ validity }
+						onChange={ ( edits ) =>
+							setData( ( prev ) => ( { ...prev, ...edits } ) )
+						}
+					/>
+				</Stack>
+			</div>
+		);
+	},
+};
+
+type HighLevelHelpTextData = {
+	name: string;
+	email: string;
+	phone: string;
+};
+
+export const HighLevelHelpText: Story = {
+	render: () => {
+		const [ data, setData ] = useState< HighLevelHelpTextData >( {
+			name: '',
+			email: '',
+			phone: '',
+		} );
+
+		const fields: Field< HighLevelHelpTextData >[] = useMemo(
+			() => [
+				{
+					id: 'name',
+					label: 'Name',
+					type: 'text',
+				},
+				{
+					id: 'email',
+					label: 'Email',
+					type: 'email',
+				},
+				{
+					id: 'phone',
+					label: 'Phone number',
+					type: 'telephone',
+				},
+			],
+			[]
+		);
+
+		const form: Form = useMemo(
+			() => ( {
+				layout: { type: 'regular' },
+				fields: [
+					{
+						id: 'accountForm',
+						label: 'Account Information',
+						description:
+							'We collect this information to create your account and provide personalized services. Your data will be kept secure and used only for account management and service improvements.',
+						children: [ 'name', 'email', 'phone' ],
+						layout: {
+							isCollapsible: false,
+							summary: 'account-form',
+							type: 'card',
+							withHeader: true,
+						},
+					},
+				],
+			} ),
+			[]
+		);
+
+		return (
+			<Stack direction="column" gap="lg">
+				<DataForm< HighLevelHelpTextData >
+					data={ data }
+					fields={ fields }
+					form={ form }
+					onChange={ ( edits ) =>
+						setData( ( prev ) => ( { ...prev, ...edits } ) )
+					}
+				/>
+			</Stack>
+		);
+	},
+};
+
+type PlaceholdersData = {
+	name: string;
+	email: string;
+	phone: string;
+};
+
+export const Placeholders: Story = {
+	render: () => {
+		const [ data, setData ] = useState< PlaceholdersData >( {
+			name: '',
+			email: '',
+			phone: '',
+		} );
+
+		const fields: Field< PlaceholdersData >[] = useMemo(
+			() => [
+				{
+					id: 'name',
+					label: 'Name',
+					type: 'text',
+					placeholder: 'Jane Doe',
+				},
+				{
+					id: 'email',
+					label: 'Email',
+					type: 'email',
+					placeholder: 'you@example.com',
+				},
+				{
+					id: 'phone',
+					label: 'Phone number',
+					type: 'telephone',
+					placeholder: '+1 (555) 123-4567',
+				},
+			],
+			[]
+		);
+
+		const form: Form = useMemo(
+			() => ( {
+				layout: { type: 'regular' },
+				fields: [ 'name', 'email', 'phone' ],
+			} ),
+			[]
+		);
+
+		return (
+			<Stack direction="column" gap="lg">
+				<DataForm< PlaceholdersData >
+					data={ data }
+					fields={ fields }
+					form={ form }
+					onChange={ ( edits ) =>
+						setData( ( prev ) => ( { ...prev, ...edits } ) )
+					}
+				/>
+			</Stack>
+		);
+	},
+};

package/src/dataform/stories/index.story.tsx

@@ -62,6 +62,11 @@ export const LayoutPanel = {
 			description: 'Chooses how to open the panel.',
 			options: [ 'default', 'dropdown', 'modal' ],
 		},
+		editVisibility: {
+			control: { type: 'select' },
+			description: 'Chooses when the edit icon is visible.',
+			options: [ 'default', 'always', 'on-hover' ],
+		},
 	},
 };
 
@@ -100,12 +105,19 @@ export const Validation = {
 		layout: {
 			control: { type: 'select' },
 			description: 'Choose the form layout type.',
-			options: [ 'regular', 'panel', 'card', 'details' ],
+			options: [
+				'regular',
+				'panel-dropdown',
+				'panel-modal',
+				'card-collapsible',
+				'card-not-collapsible',
+				'details',
+			],
 		},
 		required: {
 			control: { type: 'boolean' },
 			description:
-				'Whether or not the required validation rule is active.',
+				'Whether or not the required validation rule is active (only applies when fieldDistribution is allSame).',
 		},
 		elements: {
 			control: { type: 'select' },

package/src/dataform/stories/layout-panel.tsx

@@ -7,7 +7,13 @@ import { useMemo, useState } from '@wordpress/element';
  * Internal dependencies
  */
 import DataForm from '../index';
-import type { Field, Form, Layout, PanelLayout } from '../../types';
+import type {
+	Field,
+	Form,
+	Layout,
+	PanelLayout,
+	EditVisibility,
+} from '../../types';
 
 type SamplePost = {
 	title: string;
@@ -261,10 +267,12 @@ const getPanelLayoutFromStoryArgs = ( {
 	summary,
 	labelPosition,
 	openAs,
+	editVisibility,
 }: {
 	summary?: string[];
 	labelPosition?: 'default' | 'top' | 'side' | 'none';
 	openAs?: 'default' | 'dropdown' | 'modal';
+	editVisibility?: 'default' | EditVisibility;
 } ): Layout | undefined => {
 	const panelLayout: PanelLayout = {
 		type: 'panel',
@@ -282,16 +290,22 @@ const getPanelLayoutFromStoryArgs = ( {
 		panelLayout.summary = summary;
 	}
 
+	if ( editVisibility !== 'default' ) {
+		panelLayout.editVisibility = editVisibility;
+	}
+
 	return panelLayout;
 };
 
 const LayoutPanelComponent = ( {
 	labelPosition,
 	openAs,
+	editVisibility,
 }: {
 	type: 'default' | 'regular' | 'panel' | 'card';
 	labelPosition: 'default' | 'top' | 'side' | 'none';
 	openAs: 'default' | 'dropdown' | 'modal';
+	editVisibility: 'default' | EditVisibility;
 } ) => {
 	const [ post, setPost ] = useState< SamplePost >( {
 		title: 'Hello, World!',
@@ -321,6 +335,7 @@ const LayoutPanelComponent = ( {
 			layout: getPanelLayoutFromStoryArgs( {
 				labelPosition,
 				openAs,
+				editVisibility,
 			} ),
 			fields: [
 				'title',
@@ -357,6 +372,7 @@ const LayoutPanelComponent = ( {
 						summary: [ 'origin', 'destination', 'flight_status' ],
 						labelPosition,
 						openAs,
+						editVisibility,
 					} ),
 				},
 				{
@@ -367,11 +383,12 @@ const LayoutPanelComponent = ( {
 						summary: [ 'author', 'seat' ],
 						labelPosition,
 						openAs,
+						editVisibility,
 					} ),
 				},
 			],
 		};
-	}, [ labelPosition, openAs ] );
+	}, [ labelPosition, openAs, editVisibility ] );
 
 	return (
 		<DataForm< SamplePost >

package/src/dataform/stories/validation.tsx

@@ -86,7 +86,13 @@ const ValidationComponent = ( {
 	custom: 'sync' | 'async' | 'none';
 	pattern: boolean;
 	minMax: boolean;
-	layout: 'regular' | 'panel' | 'card' | 'details';
+	layout:
+		| 'regular'
+		| 'panel-dropdown'
+		| 'panel-modal'
+		| 'card-collapsible'
+		| 'card-not-collapsible'
+		| 'details';
 } ) => {
 	type ValidatedItem = {
 		text: string;
@@ -106,6 +112,7 @@ const ValidationComponent = ( {
 		password: string;
 		toggle?: boolean;
 		toggleGroup?: string;
+		combobox?: string;
 		date?: string;
 		dateRange?: string;
 		datetime?: string;
@@ -129,6 +136,7 @@ const ValidationComponent = ( {
 		password: 'secretpassword123',
 		toggle: undefined,
 		toggleGroup: undefined,
+		combobox: undefined,
 		date: undefined,
 		dateRange: undefined,
 		datetime: undefined,
@@ -242,6 +250,25 @@ const ValidationComponent = ( {
 						);
 						break;
 
+					case 'combobox':
+						promiseCache[ fieldId ] = new Promise( ( resolve ) =>
+							setTimeout(
+								() =>
+									resolve( [
+										{ value: 'apple', label: 'Apple' },
+										{ value: 'banana', label: 'Banana' },
+										{ value: 'cherry', label: 'Cherry' },
+										{ value: 'date', label: 'Date' },
+										{
+											value: 'elderberry',
+											label: 'Elderberry',
+										},
+									] ),
+								3500
+							)
+						);
+						break;
+
 					default:
 						throw new Error( `Unknown field ID: ${ fieldId }` );
 				}
@@ -364,6 +391,14 @@ const ValidationComponent = ( {
 			return null;
 		};
 
+		const customComboboxRule = ( value: ValidatedItem ) => {
+			if ( value.combobox !== 'apple' ) {
+				return 'Value must be Apple.';
+			}
+
+			return null;
+		};
+
 		const customPasswordRule = ( value: ValidatedItem ) => {
 			if ( value.password.length < 8 ) {
 				return 'Password must be at least 8 characters long.';
@@ -768,6 +803,48 @@ const ValidationComponent = ( {
 					custom: maybeCustomRule( customToggleGroupRule ),
 				},
 			},
+			{
+				id: 'combobox',
+				type: 'text',
+				Edit: 'combobox',
+				label: 'Combobox',
+				placeholder: 'Search and select a fruit',
+				elements:
+					elements === 'async'
+						? undefined
+						: [
+								{ value: 'apple', label: 'Apple' },
+								{ value: 'banana', label: 'Banana' },
+								{ value: 'blueberry', label: 'Blueberry' },
+								{ value: 'cherry', label: 'Cherry' },
+								{ value: 'date', label: 'Date' },
+								{ value: 'elderberry', label: 'Elderberry' },
+								{ value: 'fig', label: 'Fig' },
+								{ value: 'grape', label: 'Grape' },
+								{ value: 'honeydew', label: 'Honeydew' },
+								{ value: 'kiwi', label: 'Kiwi' },
+								{ value: 'lemon', label: 'Lemon' },
+								{ value: 'mango', label: 'Mango' },
+								{ value: 'nectarine', label: 'Nectarine' },
+								{ value: 'orange', label: 'Orange' },
+								{ value: 'papaya', label: 'Papaya' },
+								{ value: 'pear', label: 'Pear' },
+								{ value: 'quince', label: 'Quince' },
+								{ value: 'raspberry', label: 'Raspberry' },
+								{ value: 'strawberry', label: 'Strawberry' },
+								{ value: 'tangerine', label: 'Tangerine' },
+								{ value: 'watermelon', label: 'Watermelon' },
+						  ],
+				getElements:
+					elements === 'async'
+						? getElements( 'combobox' )
+						: undefined,
+				isValid: {
+					required,
+					elements: elements !== 'none' ? true : false,
+					custom: maybeCustomRule( customComboboxRule ),
+				},
+			},
 			{
 				id: 'date',
 				type: 'date',
@@ -800,7 +877,7 @@ const ValidationComponent = ( {
 				},
 			},
 		];
-	}, [ elements, custom, required, pattern, minMax, getElements ] );
+	}, [ elements, custom, pattern, minMax, getElements, required ] );
 
 	const form = useMemo( () => {
 		if ( layout === 'regular' ) {
@@ -853,6 +930,7 @@ const ValidationComponent = ( {
 					'password',
 					'textarea',
 					'select',
+					'combobox',
 					'textWithRadio',
 					'boolean',
 					'toggle',
@@ -885,7 +963,7 @@ const ValidationComponent = ( {
 			{
 				id: 'selectFields',
 				label: 'Selection Fields',
-				children: [ 'select', 'textWithRadio' ],
+				children: [ 'select', 'combobox', 'textWithRadio' ],
 			},
 			{
 				id: 'booleanFields',
@@ -901,9 +979,16 @@ const ValidationComponent = ( {
 			},
 		];
 
-		if ( layout === 'panel' ) {
+		if ( layout === 'panel-dropdown' ) {
 			return {
-				layout: { type: 'panel' as const },
+				layout: { type: 'panel' as const, openAs: 'dropdown' as const },
+				fields: groupedFields,
+			};
+		}
+
+		if ( layout === 'panel-modal' ) {
+			return {
+				layout: { type: 'panel' as const, openAs: 'modal' as const },
 				fields: groupedFields,
 			};
 		}
@@ -915,8 +1000,16 @@ const ValidationComponent = ( {
 			};
 		}
 
+		if ( layout === 'card-collapsible' ) {
+			return {
+				layout: { type: 'card' as const },
+				fields: groupedFields,
+			};
+		}
+
+		// card-not-collapsible
 		return {
-			layout: { type: 'card' as const },
+			layout: { type: 'card' as const, isCollapsible: false },
 			fields: groupedFields,
 		};
 	}, [ layout ] );
@@ -925,7 +1018,7 @@ const ValidationComponent = ( {
 
 	return (
 		<form>
-			<Stack direction="column" align="start" gap="xl">
+			<Stack direction="column" align="start" gap="3xl">
 				<DataForm< ValidatedItem >
 					data={ post }
 					fields={ _fields }

package/src/dataform/test/dataform.tsx

@@ -511,9 +511,9 @@ describe( 'DataForm component', () => {
 				/>
 			);
 
-			const titleField = screen.getByText( data.title );
+			const titleButton = fieldsSelector.title.view();
 			const user = await userEvent.setup();
-			await user.click( titleField );
+			await user.click( titleButton );
 			const titleEditField = screen.getByText(
 				'This is the Title Field'
 			);