@wordpress/dataviews 11.2.1-next.v.0 → 11.3.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="md">
+				<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="md">
+				<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="lg">
+					<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="md">
+				<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="md">
+				<DataForm< PlaceholdersData >
+					data={ data }
+					fields={ fields }
+					form={ form }
+					onChange={ ( edits ) =>
+						setData( ( prev ) => ( { ...prev, ...edits } ) )
+					}
+				/>
+			</Stack>
+		);
+	},
+};

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

@@ -100,7 +100,14 @@ 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' },

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',
@@ -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 ] );

package/src/dataviews/stories/best-practices.story.mdx

@@ -0,0 +1,55 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+import * as DataViewsStories from './index.story';
+
+<Meta of={ DataViewsStories } name="Best practices" />
+
+# Data Views
+
+Data Views allow users to display and interact with information through different layouts such as table or grid. It includes features like search, filtering, sorting, pagination, and customization options to adjust column order, items per page, and hide columns, enhancing data exploration and flexibility. 
+
+A typical flow might be:
+
+- Use search and filters to narrow down a large collection.
+- Adjust the layout and visible fields to match the task (compare, skim, or visually scan).
+- Take inline actions on item metadata, or open an editing interface when more detail is needed.
+
+## Choosing a layout
+
+### When to use **List**
+
+Use the **List** layout when:
+
+- **Content needs the most compact layout**, whether because it's used in a constrained context, or if paired with a preview surface.
+- Default information density allows for a reduced set of secondary metadata.
+- The view needs to work well in **narrow spaces**.
+
+List is a good fit for items like Pages that benefit from a live preview next to the list.
+
+### When to use **Grid**
+
+Use the **Grid** layout when:
+
+-   **Visual previews across multiple items at once are important** for recognition (patterns, templates, media, products).
+-   You want a **card‑based experience**, with each item having its own tile (image + metadata).
+-   You expect more **browsing and scanning by look** than comparing raw values.
+
+Grid works well when choosing “by look” is more important than comparing precise numbers or dates.
+
+### When to use **Table**
+
+Use the **Table** layout when:
+
+-   Users need to **compare multiple attributes across items** at once.
+-   **Column headers and alignment** are critical for understanding the data.
+-   The task involves working with structured data.
+
+Table is ideal for dense, structured information where sorting and scanning down aligned columns is the primary workflow, such as posts or comments where metadata is important for choosing the next action.
+
+## When to use something else
+
+Data Views are designed for **browsing and managing collections**. In other situations, consider other components in the `@wordpress/dataviews` package:
+
+- **Use `DataForm`** when the primary workflow primarily relates to **creating or editing a single item** at a level that doesn't require a full editor.
+- **Use `DataViewsPicker`** when the goal is **selecting one or more items** and returning that selection to another part of the UI. This is a better fit for dialogs and sidebars where the outcome is a selection, not ongoing management of a collection, e.g. inserting from a media library.
+

package/src/dataviews/stories/fixtures.tsx

@@ -377,9 +377,7 @@ export const fields: Field< SpaceObject >[] = [
 			</Stack>
 		),
 		render: ( { item } ) => {
-			return (
-				<img src={ item.image } alt="" style={ { width: '100%' } } />
-			);
+			return <img src={ item.image } alt="" />;
 		},
 	},
 	{

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Meta } from '@storybook/react-webpack5';
+import type { Meta } from '@storybook/react-vite';
 
 /**
  * Internal dependencies
@@ -11,6 +11,7 @@ import LayoutActivityComponent from './layout-activity';
 import LayoutTableComponent from './layout-table';
 import LayoutGridComponent from './layout-grid';
 import LayoutListComponent from './layout-list';
+import LayoutCustomComponent from './layout-custom';
 import InfiniteScrollComponent from './infinite-scroll';
 import WithCardComponent from './with-card';
 import FreeCompositionComponent from './free-composition';
@@ -191,6 +192,10 @@ export const LayoutActivity = {
 	},
 };
 
+export const LayoutCustom = {
+	render: LayoutCustomComponent,
+};
+
 export const Empty = {
 	render: EmptyComponent,
 	args: {