From ad741f2bc764ddfd384b5b3a392acfee6a623161 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Maneiro?=
<583546+oandregal@users.noreply.github.com>
Date: Wed, 20 Nov 2024 13:20:18 +0100
Subject: [PATCH] Update docs for actions
---
packages/dataviews/README.md | 223 ++++++++++++++++++++++++++++++++---
1 file changed, 206 insertions(+), 17 deletions(-)
diff --git a/packages/dataviews/README.md b/packages/dataviews/README.md
index 621e3c7ba71ce2..92426bf1e1f838 100644
--- a/packages/dataviews/README.md
+++ b/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: ,
+ isEligible: ( item ) => item.status === 'published'
+ callback: ( items ) => {
+ console.log( 'Viewing item:', items[0] );
+ },
+ },
+ {
+ id: 'edit',
+ label: 'Edit',
+ icon: ,
+ supportsBulk: true,
+ callback: ( items ) => {
+ console.log( 'Editing items:', items );
+ }
+ },
+ {
+ id: 'delete',
+ label: 'Delete',
+ isDestructive: true,
+ supportsBulk: true,
+ RenderModal: ( { items, closeModal, onActionPerformed } ) => (
+
+
Are you sure you want to delete { items.length } item(s)?
+
+
+ )
+ }
+];
+```
#### `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 (
+
+ );
+ }
+}
+```
+
+### `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`