@wordpress/dataviews 4.9.1-next.cd6172eb0.0 → 4.11.0

package/README.md

@@ -1,9 +1,9 @@
 # The `@wordpress/dataviews` package
 
-The DataViews package offers two React components and a few utilites to work with a list of data:
+The DataViews package offers two React components and a few utilities to work with a list of data:
 
-- `DataViews`: to render the dataset using different types of layouts (table, grid, list) and interaction capabilities (search, filters, sorting, etc.).
-- `DataForm`: to edit the items of the dataset.
+-   `DataViews`: to render the dataset using different types of layouts (table, grid, list) and interaction capabilities (search, filters, sorting, etc.).
+-   `DataForm`: to edit the items of the dataset.
 
 ## Installation
 
@@ -15,7 +15,7 @@ npm install @wordpress/dataviews --save
 
 ## `DataViews`
 
-<div class="callout callout-info">At <a href="https://wordpress.github.io/gutenberg/">WordPress Gutenberg's Storybook</a> there's and <a href="https://wordpress.github.io/gutenberg/?path=/docs/dataviews-dataviews--docs">example implementation of the Dataviews component</a>.</div>
+<div class="callout callout-info">At <a href="https://wordpress.github.io/gutenberg/">WordPress Gutenberg's Storybook</a> there's an <a href="https://wordpress.github.io/gutenberg/?path=/docs/dataviews-dataviews--docs">example implementation of the Dataviews component</a>.</div>
 
 **Important note** If you're trying to use the `DataViews` component in a WordPress plugin or theme and you're building your scripts using the `@wordpress/scripts` package, you need to import the components from `@wordpress/dataviews/wp` instead of `@wordpress/dataviews`.
 
@@ -23,13 +23,15 @@ npm install @wordpress/dataviews --save
 
 The `DataViews` component receives data and some other configuration to render the dataset. It'll call the `onChangeView` callback every time the user has interacted with the dataset in some way (sorted, filtered, changed layout, etc.):
 
-![DataViews flow](https://developer.wordpress.org/files/2024/09/368600071-20aa078f-7c3d-406d-8dd0-8b764addd22a.png "DataViews flow")
+![DataViews flow](https://developer.wordpress.org/files/2024/09/368600071-20aa078f-7c3d-406d-8dd0-8b764addd22a.png 'DataViews flow')
 
 Example:
 
 ```jsx
 const Example = () => {
-	const onChangeView = () => { /* React to user changes. */ }
+	const onChangeView = () => {
+		/* React to user changes. */
+	};
 
 	return (
 		<DataViews
@@ -45,7 +47,6 @@ const Example = () => {
 };
 ```
 
-
 ### Properties
 
 #### `data`: `Object[]`
@@ -68,13 +69,13 @@ const data = [
 ];
 ```
 
-The data can come from anywhere, from a static JSON file to a dynamic source like a HTTP Request. It's the consumer's responsiblity to query the data source appropiately and update the dataset based on the user's choices for sorting, filtering, etc.
+The data can come from anywhere, from a static JSON file to a dynamic source like an HTTP Request. It's the consumer's responsibility to query the data source appropriately and update the dataset based on the user's choices for sorting, filtering, etc.
 
 Each record should have an `id` that identifies them uniquely. If they don't, the consumer should provide the `getItemId` property to `DataViews`: a function that returns an unique identifier for the record.
 
 #### `getItemId`: `function`
 
-Function that receives an item and returns an unique identifier for it.
+A function that receives an item and returns a unique identifier for it.
 
 It's optional. The field will get a default implementation by `DataViews` that returns the value of the `item[ id ]`.
 
@@ -87,6 +88,19 @@ Example:
 }
 ```
 
+#### `getItemLevel`: `function`
+
+A function that receives an item and returns its hierarchical level. It's optional, but this property must be passed for DataViews to display the hierarchical levels of the data if `view.showLevels` is true.
+
+Example:
+
+```js
+// Example implementation
+{
+	getItemLevel={ ( item ) => item.level }
+}
+```
+
 #### `fields`: `Object[]`
 
 The fields describe the visible items for each record in the dataset and how they behave (how to sort them, display them, etc.). See "Fields API" for a description of every property.
@@ -165,6 +179,7 @@ const view = {
 		field: 'date',
 		direction: 'desc',
 	},
+	titleField: 'title',
 	fields: [ 'author', 'status' ],
 	layout: {},
 };
@@ -185,54 +200,28 @@ Properties:
     -   `field`: the field used for sorting the dataset.
     -   `direction`: the direction to use for sorting, one of `asc` or `desc`.
 
--   `fields`: a list of field `id` that are visible in the UI and the specific order in which they are displayed.
+-   `titleField`: The id of the field representing the title of the record.
+-   `mediaField`: The id of the field representing the media of the record.
+-   `descriptionField`: The id of the field representing the description of the record.
+-   `showTitle`: Whether the title should be shown in the UI. `true` by default.
+-   `showMedia`: Whether the media should be shown in the UI. `true` by default.
+-   `showDescription`: Whether the description should be shown in the UI. `true` by default.
+-   `showLevels`: Whether to display the hierarchical levels for the data. `false` by default. See related `getItemLevel` DataView prop.
+-   `fields`: a list of remaining field `id` that are visible in the UI and the specific order in which they are displayed.
 -   `layout`: config that is specific to a particular layout type.
 
 ##### Properties of `layout`
 
-| Properties of `layout`                                                                                          | Table | Grid | List |
-| --------------------------------------------------------------------------------------------------------------- | ----- | ---- | ---- |
-| `primaryField`: the field's `id` to be highlighted in each layout. It's not hidable.                            | ✓     | ✓    | ✓    |
-| `mediaField`: the field's `id` to be used for rendering each card's media. It's not hiddable.                   |       | ✓    | ✓    |
-| `columnFields`: a list of field's `id` to render vertically stacked instead of horizontally (the default).      |       | ✓    |      |
-| `badgeFields`: a list of field's `id` to render without label and styled as badges.                             |       | ✓    |      |
-| `combinedFields`: a list of "virtual" fields that are made by combining others. See "Combining fields" section. | ✓     |      |      |
-| `styles`: additional `width`, `maxWidth`, `minWidth` styles for each field column.                              | ✓     |      |      |
-
-##### Combining fields
-
-The `table` layout has the ability to create "virtual" fields that are made out by combining existing ones.
-
-Each "virtual field", has to provide an `id` and `label` (optionally a `header` instead), which have the same meaning as any other field.
-
-Additionally, they need to provide:
-
--   `children`: a list of field's `id` to combine
--   `direction`: how should they be stacked, `vertical` or `horizontal`
-
-For example, this is how you'd define a `site` field which is a combination of a `title` and `description` fields, which are not displayed:
-
-```js
-{
-	fields: [ 'site', 'status' ],
-	layout: {
-		combinedFields: [
-			{
-				id: 'site',
-				label: 'Site',
-				children: [ 'title', 'description' ],
-				direction: 'vertical',
-			}
-		]
-	}
-}
-```
+| Properties of `layout`                                                              | Table | Grid | List |
+| ----------------------------------------------------------------------------------- | ----- | ---- | ---- |
+| `badgeFields`: a list of field's `id` to render without label and styled as badges. |       | ✓    |      |
+| `styles`: additional `width`, `maxWidth`, `minWidth` styles for each field column.  | ✓     |      |      |
 
 #### `onChangeView`: `function`
 
 Callback executed when the view has changed. It receives the new view object as a parameter.
 
-The view is a representation of the visible state of the dataset: what type of layout is used to display it (table, grid, etc.), how the dataset is filtered, how it is sorted or paginated. It's the consumer's responsibility to use the view config to query the data provider and make sure the user decisions (sort, pagination, filters, etc.) are respected.
+The view is a representation of the visible state of the dataset: what type of layout is used to display it (table, grid, etc.), how the dataset is filtered, and how it is sorted or paginated. The consumer is responsible for using the view config to query the data provider and ensure the user decisions (sort, pagination, filters, etc.) are respected.
 
 The following example shows how a view object is used to query the WordPress REST API via the entities abstraction. The same can be done with any other data provider.
 
@@ -255,6 +244,7 @@ function MyCustomPageTable() {
 				value: [ 'publish', 'draft' ],
 			},
 		],
+		titleField: 'title',
 		fields: [ 'author', 'status' ],
 		layout: {},
 	} );
@@ -328,8 +318,8 @@ const actions = [
 		RenderModal: ( { items, closeModal, onActionPerformed } ) => (
 			<div>
 				<p>Are you sure you want to delete { items.length } item(s)?</p>
-				<Button 
-					variant="primary" 
+				<Button
+					variant="primary"
 					onClick={() => {
 						console.log( 'Deleting items:', items );
 						onActionPerformed();
@@ -363,39 +353,40 @@ Whether the data is loading. `false` by default.
 
 #### `defaultLayouts`: `Record< string, view >`
 
-This property provides layout information about the view types that are active. If empty, enables all layout types (see "Layout Types") with empty layout data.
+This property provides layout information about active view types. If empty, this enables all layout types (see "Layout Types") with empty layout data.
 
 For example, this is how you'd enable only the table view type:
 
 ```js
 const defaultLayouts = {
 	table: {
-		layout: {
-			primaryField: 'my-key',
-		},
+		showMedia: false,
+	},
+	grid: {
+		showMedia: true,
 	},
 };
 ```
 
-The `defaultLayouts` property should be an object that includes properties named `table`, `grid`, or `list`. Each of these properties should contain a `layout` property, which holds the configuration for each specific layout type. Check "Properties of layout" for the full list of properties available for each layout's configuration
+The `defaultLayouts` property should be an object that includes properties named `table`, `grid`, or `list`. These properties are applied to the view object each time the user switches to the corresponding layout.
 
 #### `selection`: `string[]`
 
 The list of selected items' ids.
 
-If `selection` and `onChangeSelection` are provided, the `DataViews` component behaves as a controlled component, otherwise, it behaves like an uncontrolled component.
+If `selection` and `onChangeSelection` are provided, the `DataViews` component behaves like a controlled component. Otherwise, it behaves like an uncontrolled component.
 
 #### `onChangeSelection`: `function`
 
-Callback that signals the user selected one of more items. It receives the list of selected items' ids as a parameter.
+Callback that signals the user selected one of more items. It receives the list of selected items' IDs as a parameter.
 
-If `selection` and `onChangeSelection` are provided, the `DataViews` component behaves as a controlled component, otherwise, it behaves like an uncontrolled component.
+If `selection` and `onChangeSelection` are provided, the `DataViews` component behaves like a controlled component. Otherwise, it behaves like an uncontrolled component.
 
-### `isItemClickable`: `function`
+#### `isItemClickable`: `function`
 
-A function that determines if a media field or a primary field are clickable. It receives an item as an argument and returns a boolean value indicating whether the item can be clicked.
+A function that determines if a media field or a primary field is clickable. It receives an item as an argument and returns a boolean value indicating whether the item can be clicked.
 
-### `onClickItem`: `function`
+#### `onClickItem`: `function`
 
 A callback function that is triggered when a user clicks on a media field or primary field. This function is currently implemented only in the `grid` and `list` views.
 
@@ -420,8 +411,8 @@ const Example = () => {
 			form={ form }
 			onChange={ onChange }
 		/>
-	)
-}
+	);
+};
 ```
 
 ### Properties
@@ -430,7 +421,7 @@ const Example = () => {
 
 A single item to be edited.
 
-It can be think of as a single record coming from the `data` property of `DataViews` — though it doesn't need to be. It can be totally separated or a mix of records if your app supports bulk editing.
+It can be thought of as a single record coming from the `data` property of `DataViews` — though it doesn't need to be. It can be totally separated or a mix of records if your app supports bulk editing.
 
 #### `fields`: `Object[]`
 
@@ -464,8 +455,30 @@ const fields = [
 
 #### `form`: `Object[]`
 
-- `type`: either `regular` or `panel`.
-- `fields`: a list of fields ids that should be rendered.
+-   `type`: either `regular` or `panel`.
+-   `labelPosition`: either `side`, `top`, or `none`.
+-   `fields`: a list of fields ids that should be rendered. Field ids can also be defined as an object and allow you to define a `layout`, `labelPosition` or `children` if displaying combined fields. See "Form Field API" for a description of every property.
+
+Example:
+
+```js
+const form = {
+	type: 'panel',
+	fields: [
+		'title',
+		'data',
+		{
+			id: 'status',
+			label: 'Status & Visibility',
+			children: [ 'status', 'password' ],
+		},
+		{
+			id: 'featured_media',
+			layout: 'regular',
+		},
+	],
+};
+```
 
 #### `onChange`: `function`
 
@@ -496,10 +509,10 @@ const onChange = ( edits ) => {
 
 return (
 	<DataForm
-		data={data}
-		fields={fields}
-		form={form}
-		onChange={onChange}
+		data={ data }
+		fields={ fields }
+		form={ form }
+		onChange={ onChange }
 	/>
 );
 ```
@@ -512,26 +525,26 @@ Utility to apply the view config (filters, search, sorting, and pagination) to a
 
 Parameters:
 
-- `data`: the dataset, as described in the "data" property of DataViews.
-- `view`: the view config, as described in the "view" property of DataViews.
-- `fields`: the fields config, as described in the "fields" property of DataViews.
+-   `data`: the dataset, as described in the "data" property of DataViews.
+-   `view`: the view config, as described in the "view" property of DataViews.
+-   `fields`: the fields config, as described in the "fields" property of DataViews.
 
 Returns an object containing:
 
-- `data`: the new dataset, with the view config applied.
-- `paginationInfo`: object containing the following properties:
-	- `totalItems`: total number of items for the current view config.
-	- `totalPages`: total number of pages for the current view config.
+-   `data`: the new dataset, with the view config applied.
+-   `paginationInfo`: object containing the following properties:
+    -   `totalItems`: total number of items for the current view config.
+    -   `totalPages`: total number of pages for the current view config.
 
 ### `isItemValid`
 
-Utility to determine whether or not the given item's value is valid according to the current fields and form config.
+Utility is used to determine whether or not the given item's value is valid according to the current fields and form configuration.
 
 Parameters:
 
-- `item`: the item, as described in the "data" property of DataForm.
-- `fields`: the fields config, as described in the "fields" property of DataForm.
-- `form`: the form config, as described in the "form" property of DataForm.
+-   `item`: the item, as described in the "data" property of DataForm.
+-   `fields`: the fields config, as described in the "fields" property of DataForm.
+-   `form`: the form config, as described in the "form" property of DataForm.
 
 Returns a boolean indicating if the item is valid (true) or not (false).
 
@@ -541,17 +554,17 @@ Returns a boolean indicating if the item is valid (true) or not (false).
 
 The unique identifier of the action.
 
-- Type: `string`
-- Required
-- Example: `move-to-trash`
+-   Type: `string`
+-   Required
+-   Example: `move-to-trash`
 
-### `label` 
+### `label`
 
 The user facing description of the action.
 
-- Type: `string | function`
-- Required
-- Example:
+-   Type: `string | function`
+-   Required
+-   Example:
 
 ```js
 {
@@ -563,7 +576,7 @@ or
 
 ```js
 {
-	label: ( items ) => items.length > 1 ? 'Delete items' : 'Delete item'
+	label: ( items ) => ( items.length > 1 ? 'Delete items' : 'Delete item' );
 }
 ```
 
@@ -571,27 +584,27 @@ or
 
 Whether the action should be displayed inline (primary) or only displayed in the "More actions" menu (secondary).
 
-- Type: `boolean`
-- Optional
+-   Type: `boolean`
+-   Optional
 
 ### `icon`
 
 Icon to show for primary actions.
 
-- Type: SVG element
-- Required for primary actions, optional for secondary actions.
+-   Type: SVG element
+-   Required for primary actions, optional for secondary actions.
 
 ### `isEligible`
 
 Function that determines whether the action can be performed for a given record.
 
-- Type: `function`
-- Optional. If not present, action is considered eligible for all items.
-- Example:
+-   Type: `function`
+-   Optional. If not present, action is considered eligible for all items.
+-   Example:
 
 ```js
 {
-	isEligible: ( item ) => item.status === 'published'
+	isEligible: ( item ) => item.status === 'published';
 }
 ```
 
@@ -599,47 +612,47 @@ Function that determines whether the action can be performed for a given record.
 
 Whether the action can delete data, in which case the UI communicates it via a red color.
 
-- Type: `boolean`
-- Optional
+-   Type: `boolean`
+-   Optional
 
 ### `supportsBulk`
 
 Whether the action can operate over multiple items at once.
 
-- Type: `boolean`
-- Optional
-- Default: `false`
+-   Type: `boolean`
+-   Optional
+-   Default: `false`
 
 ### `disabled`
 
 Whether the action is disabled.
 
-- Type: `boolean`
-- Optional
-- Default: `false`
+-   Type: `boolean`
+-   Optional
+-   Default: `false`
 
 ### `context`
 
 Where this action would be visible.
 
-- Type: `string`
-- Optional
-- One of: `list`, `single`
+-   Type: `string`
+-   Optional
+-   One of: `list`, `single`
 
 ### `callback`
 
 Function that performs the required action.
 
-- Type: `function`
-- Either `callback` or `RenderModal` must be provided. If `RenderModal` is provided, `callback` will be ignored
-- Example:
+-   Type: `function`
+-   Either `callback` or `RenderModal` must be provided. If `RenderModal` is provided, `callback` will be ignored
+-   Example:
 
 ```js
 {
 	callback: ( items, { onActionPerformed } ) => {
 		// Perform action.
 		onActionPerformed?.( items );
-	}
+	};
 }
 ```
 
@@ -647,9 +660,9 @@ Function that performs the required action.
 
 Component to render UI in a modal for the action.
 
-- Type: `ReactElement`
-- Either `callback` or `RenderModal` must be provided. If `RenderModal` is provided, `callback` will be ignored.
-- Example:
+-   Type: `ReactElement`
+-   Either `callback` or `RenderModal` must be provided. If `RenderModal` is provided, `callback` will be ignored.
+-   Example:
 
 ```jsx
 {
@@ -673,7 +686,7 @@ Component to render UI in a modal for the action.
 				</HStack>
 			</form>
 		);
-	}
+	};
 }
 ```
 
@@ -681,17 +694,16 @@ Component to render UI in a modal for the action.
 
 Controls visibility of the modal's header when using `RenderModal`.
 
-- Type: `boolean`
-- Optional
-- When false and using `RenderModal`, the action's label is used in modal header
+-   Type: `boolean`
+-   Optional
+-   When false and using `RenderModal`, the action's label is used in modal header
 
 ### `modalHeader`
 
 The header text to show in the modal.
 
-- Type: `string`
-- Optional
-
+-   Type: `string`
+-   Optional
 
 ## Fields API
 
@@ -699,78 +711,88 @@ The header text to show in the modal.
 
 The unique identifier of the field.
 
-- Type: `string`.
-- Required.
+-   Type: `string`.
+-   Required.
 
 Example:
 
 ```js
-{ id: 'field_id' }
+{
+	id: 'field_id';
+}
 ```
 
 ### `type`
 
 Field type. One of `text`, `integer`, `datetime`.
 
-If a field declares a `type`, it gets default implementations for the `sort`, `isValid`, and `Edit` functions. They will overriden if the field provides its own.
+If a field declares a `type`, it gets default implementations for the `sort`, `isValid`, and `Edit` functions if no other values are specified.
 
-- Type: `string`.
-- Optional.
+-   Type: `string`.
+-   Optional.
 
 Example:
 
 ```js
-{ type: 'text' }
+{
+	type: 'text';
+}
 ```
 
 ### `label`
 
 The field's name. This will be used across the UI.
 
-- Type: `string`.
-- Optional.
-- Defaults to the `id` value.
+-   Type: `string`.
+-   Optional.
+-   Defaults to the `id` value.
 
 Example:
 
 ```js
-{ label: 'Title' }
+{
+	label: 'Title';
+}
 ```
 
 ### `header`
 
 React component used by the layouts to display the field name — useful to add icons, etc. It's complementary to the `label` property.
 
-- Type: React component.
-- Optional.
-- Defaults to the `label` value.
-- Props: none.
-- Returns a React element that represents the field's name.
+-   Type: React component.
+-   Optional.
+-   Defaults to the `label` value.
+-   Props: none.
+-   Returns a React element that represents the field's name.
 
 Example:
 
 ```js
 {
-	header: () => { /* Returns a react element. */ }
+	header: () => {
+		/* Returns a react element. */
+	};
 }
 ```
 
 ### `getValue`
 
-React component that returns the value of a field. This value is used in sorting the fields, or when filtering.
+React component that returns the value of a field. This value is used to sort or filter the fields.
 
-- Type: React component.
-- Optional.
-- Defaults to `item[ id ]`.
-- Props:
-  - `item` value to be processed.
-- Returns a value that represents the field.
+-   Type: React component.
+-   Optional.
+-   Defaults to `item[ id ]`.
+-   Props:
+    -   `item` value to be processed.
+-   Returns a value that represents the field.
 
 Example:
 
 ```js
 {
-	getValue: ( { item } ) => { /* The field's value.  */ };
+	getValue: ( { item } ) => {
+		/* The field's value.  */
+	};
 }
 ```
 
@@ -778,18 +800,20 @@ Example:
 
 React component that renders the field. This is used by the layouts.
 
-- Type: React component.
-- Optional.
-- Defaults to `getValue`.
-- Props
-  - `item` value to be processed.
-- Returns a React element that represents the field's value.
+-   Type: React component.
+-   Optional.
+-   Defaults to `getValue`.
+-   Props
+    -   `item` value to be processed.
+-   Returns a React element that represents the field's value.
 
 Example:
 
 ```js
 {
-	render: ( { item} ) => { /* React element to be displayed. */ }
+	render: ( { item } ) => {
+		/* React element to be displayed. */
+	};
 }
 ```
 
@@ -797,26 +821,21 @@ Example:
 
 React component that renders the control to edit the field.
 
-- Type: React component | `string`. If it's a string, it needs to be one of `text`, `integer`, `datetime`, `radio`, `select`.
-- Required by DataForm. Optional if the field provided a `type`.
-- Props:
-  - `data`: the item to be processed
-  - `field`: the field definition
-  - `onChange`: the callback with the updates
-  - `hideLabelFromVision`: boolean representing if the label should be hidden
-- Returns a React element to edit the field's value.
+-   Type: React component | `string`. If it's a string, it needs to be one of `text`, `integer`, `datetime`, `radio`, `select`.
+-   Required by DataForm. Optional if the field provided a `type`.
+-   Props:
+    -   `data`: the item to be processed
+    -   `field`: the field definition
+    -   `onChange`: the callback with the updates
+    -   `hideLabelFromVision`: boolean representing if the label should be hidden
+-   Returns a React element to edit the field's value.
 
 Example:
 
 ```js
 // A custom control defined by the field.
 {
-	Edit: ( {
-		data,
-		field,
-		onChange,
-		hideLabelFromVision
-	} ) => {
+	Edit: ( { data, field, onChange, hideLabelFromVision } ) => {
 		const value = field.getValue( { item: data } );
 
 		return (
@@ -826,14 +845,14 @@ Example:
 				hideLabelFromVision
 			/>
 		);
-	}
+	};
 }
 ```
 
 ```js
 // Use one of the core controls.
 {
-	Edit: 'radio'
+	Edit: 'radio';
 }
 ```
 
@@ -841,7 +860,7 @@ Example:
 // Edit is optional when field's type is present.
 // The field will use the default Edit function for text.
 {
-	type: 'text'
+	type: 'text';
 }
 ```
 
@@ -858,16 +877,16 @@ Example:
 
 Function to sort the records.
 
-- Type: `function`.
-- Optional.
-- Args
-  - `a`: the first item to compare
-  - `b`: the second item to compare
-  - `direction`: either `asc` (ascending) or `desc` (descending)
-- Returns a number where:
-  - a negative value indicates that `a` should come before `b`
-  - a positive value indicates that `a` should come after `b`
-  - 0 indicates that `a` and `b` are considered equal
+-   Type: `function`.
+-   Optional.
+-   Args
+    -   `a`: the first item to compare
+    -   `b`: the second item to compare
+    -   `direction`: either `asc` (ascending) or `desc` (descending)
+-   Returns a number where:
+    -   a negative value indicates that `a` should come before `b`
+    -   a positive value indicates that `a` should come after `b`
+    -   0 indicates that `a` and `b` are considered equal
 
 Example:
 
@@ -878,7 +897,7 @@ Example:
 		return direction === 'asc'
 			? a.localeCompare( b )
 			: b.localeCompare( a );
-	}
+	};
 }
 ```
 
@@ -886,7 +905,7 @@ Example:
 // If field type is provided,
 // the field gets a default sort function.
 {
-	type: 'number'
+	type: 'number';
 }
 ```
 
@@ -894,8 +913,10 @@ Example:
 // Even if a field type is provided,
 // fields can override the default sort function assigned for that type.
 {
-	type: 'number'
-	sort: ( a, b, direction ) => { /* Custom sort */ }
+	type: 'number';
+	sort: ( a, b, direction ) => {
+		/* Custom sort */
+	};
 }
 ```
 
@@ -903,13 +924,13 @@ Example:
 
 Function to validate a field's value.
 
-- Type: function.
-- Optional.
-- Args
-  - `item`: the data to validate
-  - `context`: an object containing the following props:
-    - `elements`: the elements defined by the field
-- Returns a boolean, indicating if the field is valid or not.
+-   Type: function.
+-   Optional.
+-   Args
+    -   `item`: the data to validate
+    -   `context`: an object containing the following props:
+        -   `elements`: the elements defined by the field
+-   Returns a boolean, indicating if the field is valid or not.
 
 Example:
 
@@ -918,7 +939,7 @@ Example:
 {
 	isValid: ( item, context ) => {
 		return !! item;
-	}
+	};
 }
 ```
 
@@ -943,18 +964,20 @@ Example:
 
 Function that indicates if the field should be visible.
 
-- Type: `function`.
-- Optional.
-- Args
-  - `item`: the data to be processed
-- Returns a `boolean` indicating if the field should be visible (`true`) or not (`false`).
+-   Type: `function`.
+-   Optional.
+-   Args
+    -   `item`: the data to be processed
+-   Returns a `boolean` indicating if the field should be visible (`true`) or not (`false`).
 
 Example:
 
 ```js
 // Custom isVisible function.
 {
-	isVisible: ( item ) => { /* Custom implementation. */ }
+	isVisible: ( item ) => {
+		/* Custom implementation. */
+	};
 }
 ```
 
@@ -962,54 +985,60 @@ Example:
 
 Boolean indicating if the field is sortable.
 
-- Type: `boolean`.
-- Optional.
-- Defaults to `true`.
+-   Type: `boolean`.
+-   Optional.
+-   Defaults to `true`.
 
 Example:
 
 ```js
-{ enableSorting: true }
+{
+	enableSorting: true;
+}
 ```
 
 ### `enableHiding`
 
 Boolean indicating if the field can be hidden.
 
-- Type: `boolean`.
-- Optional.
-- Defaults to `true`.
+-   Type: `boolean`.
+-   Optional.
+-   Defaults to `true`.
 
 Example:
 
 ```js
-{ enableHiding: true }
+{
+	enableHiding: true;
+}
 ```
 
 ### `enableGlobalSearch`
 
 Boolean indicating if the field is searchable.
 
-- Type: `boolean`.
-- Optional.
-- Defaults to `false`.
+-   Type: `boolean`.
+-   Optional.
+-   Defaults to `false`.
 
 Example:
 
 ```js
-{ enableGlobalSearch: true }
+{
+	enableGlobalSearch: true;
+}
 ```
 
 ### `elements`
 
-List of valid values for a field. If provided, it creates a DataViews' filter for the field. DataForm's edit control will use these values as well (see `Edit` field property).
+List of valid values for a field. If provided, it creates a DataViews' filter for the field. DataForm's edit control will also use these values. (See `Edit` field property.)
 
-- Type: `array` of objects.
-- Optional.
-- Each object can have the following properties:
-  - `value`: required, the value to match against the field's value.
-  - `label`: required, the name to display to users.
-  - `description`: optional, a longer description of the item.
+-   Type: `array` of objects.
+-   Optional.
+-   Each object can have the following properties:
+    -   `value`: the value to match against the field's value. (Required)
+    -   `label`: the name to display to users. (Required)
+    -   `description`: optional, a longer description of the item.
 
 Example:
 
@@ -1020,7 +1049,7 @@ Example:
 		{ value: '2', label: 'Product B' },
 		{ value: '3', label: 'Product C' },
 		{ value: '4', label: 'Product D' },
-	]
+	];
 }
 ```
 
@@ -1028,11 +1057,11 @@ Example:
 
 Configuration of the filters.
 
-- Type: `object`.
-- Optional.
-- Properties:
-  - `operators`: the list of operators supported by the field. See "operators" below. By default, a filter will support the `isAny` and `isNone` multi-selection operators.
-  - `isPrimary`: boolean, optional. Indicates if the filter is primary. A primary filter is always visible and is not listed in the "Add filter" component, except for the list layout where it behaves like a secondary filter.
+-   Type: `object`.
+-   Optional.
+-   Properties:
+    -   `operators`: the list of operators supported by the field. See "operators" below. A filter will support the `isAny` and `isNone` multi-selection operators by default.
+    -   `isPrimary`: boolean, optional. Indicates if the filter is primary. A primary filter is always visible and is not listed in the "Add filter" component, except for the list layout where it behaves like a secondary filter.
 
 Operators:
 
@@ -1045,7 +1074,7 @@ Operators:
 | `isAll`    | Multiple items | `AND`. The item's field has all of the values in the list.              | Category is all: Book, Review, Science Fiction     |
 | `isNotAll` | Multiple items | `NOT AND`. The item's field doesn't have all of the values in the list. | Category is not all: Book, Review, Science Fiction |
 
-`is` and `isNot` are single-selection operators, while `isAny`, `isNone`, `isAll`, and `isNotALl` are multi-selection. By default, a filter with no operators declared will support the `isAny` and `isNone` multi-selection operators. A filter cannot mix single-selection & multi-selection operators; if a single-selection operator is present in the list of valid operators, the multi-selection ones will be discarded and the filter won't allow selecting more than one item.
+`is` and `isNot` are single-selection operators, while `isAny`, `isNone`, `isAll`, and `isNotALl` are multi-selection. A filter with no operators declared will support the `isAny` and `isNone` multi-selection operators by default. A filter cannot mix single-selection & multi-selection operators; if a single-selection operator is present in the list of valid operators, the multi-selection ones will be discarded, and the filter won't allow selecting more than one item.
 
 Example:
 
@@ -1053,7 +1082,7 @@ Example:
 // Set a filter as primary.
 {
 	filterBy: {
-		isPrimary: true
+		isPrimary: true;
 	}
 }
 ```
@@ -1062,7 +1091,7 @@ Example:
 // Configure a filter as single-selection.
 {
 	filterBy: {
-		operators: [ `is`, `isNot` ]
+		operators: [ `is`, `isNot` ];
 	}
 }
 ```
@@ -1071,11 +1100,91 @@ Example:
 // Configure a filter as multi-selection with all the options.
 {
 	filterBy: {
-		operators: [ `isAny`, `isNone`, `isAll`, `isNotAll` ]
+		operators: [ `isAny`, `isNone`, `isAll`, `isNotAll` ];
 	}
 }
 ```
 
+## Form Field API
+
+### `id`
+
+The unique identifier of the field.
+
+-   Type: `string`.
+-   Required.
+
+Example:
+
+```js
+{
+	id: 'field_id';
+}
+```
+
+### `layout`
+
+The same as the `form.type`, either `regular` or `panel` only for the individual field. It defaults to `form.type`.
+
+-   Type: `string`.
+
+Example:
+
+```js
+{
+	id: 'field_id',
+	layout: 'regular'
+}
+```
+
+### `labelPosition`
+
+The same as the `form.labelPosition`, either `side`, `top`, or `none` for the individual field. It defaults to `form.labelPosition`.
+
+-   Type: `string`.
+
+Example:
+
+```js
+{
+	id: 'field_id',
+	labelPosition: 'none'
+}
+```
+
+### `label`
+
+The label used when displaying a combined field, this requires the use of `children` as well.
+
+-   Type: `string`.
+
+Example:
+
+```js
+{
+	id: 'field_id',
+	label: 'Combined Field',
+	children: [ 'field1', 'field2' ]
+}
+```
+
+### `children`
+
+Groups a set of fields defined within children. For example if you want to display multiple fields within the Panel dropdown you can use children ( see example ).
+
+-   Type: `Array< string | FormField >`.
+
+Example:
+
+```js
+{
+	id: 'status',
+	layout: 'panel',
+	label: 'Combined Field',
+	children: [ 'field1', 'field2' ],
+}
+```
+
 ## Contributing to this package
 
 This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.