DataViews: reorganize docs for actions

packages/dataviews/README.md

@@ -293,23 +293,54 @@ function MyCustomPageTable() {
 
 #### `actions`: `Object[]`
 
-Collection of operations that can be performed upon each record.
-
-Each action is an object with the following properties:
-
--   `id`: string, required. Unique identifier of the action. For example, `move-to-trash`.
--   `label`: string|function, required. User facing description of the action. For example, `Move to Trash`. It can also take a function that takes the selected items as a parameter and returns a string: this can be useful to provide a dynamic label based on the selection.
--   `isPrimary`: boolean, optional. Whether the action should be listed inline (primary) or in hidden in the more actions menu (secondary).
--   `icon`: SVG element. Icon to show for primary actions. It's required for a primary action, otherwise the action would be considered secondary.
--   `isEligible`: function, optional. Whether the action can be performed for a given record. If not present, the action is considered to be eligible for all items. It takes the given record as input.
--   `isDestructive`: boolean, optional. Whether the action can delete data, in which case the UI would communicate it via red color.
--   `supportsBulk`: Whether the action can be used as a bulk action. False by default.
--   `disabled`: Whether the action is disabled. False by default.
--   `context`: where this action would be visible. One of `list`, `single`.
--   `callback`: function, required unless `RenderModal` is provided. Callback function that takes as input the list of items to operate with, and performs the required action.
--   `RenderModal`: ReactElement, optional. If an action requires that some UI be rendered in a modal, it can provide a component which takes as input the the list of `items` to operate with, `closeModal` function, and `onActionPerformed` function. When this prop is provided, the `callback` property is ignored.
--   `hideModalHeader`: boolean, optional. This property is used in combination with `RenderModal` and controls the visibility of the modal's header. If the action renders a modal and doesn't hide the header, the action's label is going to be used in the modal's header.
--   `modalHeader`: string, optional. The header of the modal.
+A list of actions that can be performed on the dataset. See "Actions API" for more details.
+
+Example:
+
+```js
+const actions = [
+	{
+		id: 'view',
+		label: 'View',
+		isPrimary: true,
+		icon: <Icon icon={ view } />,
+		isEligible: ( item ) => item.status === 'published'
+		callback: ( items ) => {
+			console.log( 'Viewing item:', items[0] );
+		},
+	},
+	{
+		id: 'edit',
+		label: 'Edit',
+		icon: <Icon icon={ edit } />,
+		supportsBulk: true,
+		callback: ( items ) => {
+			console.log( 'Editing items:', items );
+		}
+	},
+	{
+		id: 'delete',
+		label: 'Delete',
+		isDestructive: true,
+		supportsBulk: true,
+		RenderModal: ( { items, closeModal, onActionPerformed } ) => (
+			<div>
+				<p>Are you sure you want to delete { items.length } item(s)?</p>
+				<Button 
+					variant="primary" 
+					onClick={() => {
+						console.log( 'Deleting items:', items );
+						onActionPerformed();
+						closeModal();
+					}}
+				>
+					Confirm Delete
+				</Button>
+			</div>
+		)
+	}
+];
+```
 
 #### `paginationInfo`: `Object`
 
@@ -502,6 +533,164 @@ Parameters:
 
 Returns a boolean indicating if the item is valid (true) or not (false).
 
+## Actions API
+
+### `id`
+
+The unique identifier of the action.
+
+- Type: `string`
+- Required
+- Example: `move-to-trash`
+
+### `label` 
+
+The user facing description of the action.
+
+- Type: `string | function`
+- Required
+- Example:
+
+```js
+{
+	label: Move to Trash
+}
+```
+
+or
+
+```js
+{
+	label: ( items ) => items.length > 1 ? 'Delete items' : 'Delete item'
+}
+```
+
+### `isPrimary`
+
+Whether the action should be displayed inline (primary) or only displayed in the "More actions" menu (secondary).
+
+- Type: `boolean`
+- Optional
+
+### `icon`
+
+Icon to show for primary 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:
+
+```js
+{
+	isEligible: ( item ) => item.status === 'published'
+}
+```
+
+### `isDestructive`
+
+Whether the action can delete data, in which case the UI communicates it via a red color.
+
+- Type: `boolean`
+- Optional
+
+### `supportsBulk`
+
+Whether the action can operate over multiple items at once.
+
+- Type: `boolean`
+- Optional
+- Default: `false`
+
+### `disabled`
+
+Whether the action is disabled.
+
+- Type: `boolean`
+- Optional
+- Default: `false`
+
+### `context`
+
+Where this action would be visible.
+
+- 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:
+
+```js
+{
+	callback: ( items, { onActionPerformed } ) => {
+		// Perform action.
+		onActionPerformed?.( items );
+	}
+}
+```
+
+### `RenderModal`
+
+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:
+
+```jsx
+{
+	RenderModal: ( { items, closeModal, onActionPerformed } ) => {
+		const onSubmit = ( event ) => {
+			event.preventDefault();
+			// Perform action.
+			closeModal?.();
+			onActionPerformed?.( items );
+		};
+		return (
+			<form onSubmit={ onSubmit }>
+				<p>Modal UI</p>
+				<HStack>
+					<Button variant="tertiary" onClick={ closeModal }>
+						Cancel
+					</Button>
+					<Button variant="primary" type="submit">
+						Submit
+					</Button>
+				</HStack>
+			</form>
+		);
+	}
+}
+```
+
+### `hideModalHeader`
+
+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
+
+### `modalHeader`
+
+The header text to show in the modal.
+
+- Type: `string`
+- Optional
+
+
 ## Fields API
 
 ### `id`