diff --git a/packages/dataviews/README.md b/packages/dataviews/README.md
index 95b8fc898555c..066a32fc40f47 100644
--- a/packages/dataviews/README.md
+++ b/packages/dataviews/README.md
@@ -1,10 +1,9 @@
-# DataViews
+# The `@wordpress/dataviews` package
-DataViews is a component that provides an API to render datasets using different types of layouts (table, grid, list, etc.).
+The DataViews package offers two components to work with a given dataset:
-DataViews is data agnostic, it can work with data coming from a static (JSON file) or dynamic source (HTTP Request) — it just requires the data to be an array of objects that have an unique identifier. Consumers are responsible to query the data source appropiately based on the DataViews props:
-
-
+- `DataViews`: allows rendering a dataset using different types of layouts (table, grid, list) and interaction capabilities (search, filters, sorting, etc.).
+- `DataForm`: allows editing the items from the same dataset.
## Installation
@@ -14,7 +13,13 @@ Install the module
npm install @wordpress/dataviews --save
```
-## Usage
+## `DataViews`
+
+### Usage
+
+The component is data agnostic, it just requires the data to be an array of objects with an unique identifier — it can work with data coming from a static (e.g.: JSON file) or dynamic source (e.g.: HTTP Request). Consumers are responsible to query the data source appropiately:
+
+
```jsx
const Example = () => {
@@ -34,11 +39,11 @@ const Example = () => {
};
```
-
+
-## Properties
+### Properties
-### `data`: `Object[]`
+#### `data`: `Object[]`
The dataset to work with, represented as a one-dimensional array.
@@ -60,7 +65,7 @@ const data = [
By default, dataviews would use each record's `id` as an unique identifier. If it's not, the consumer should provide a `getItemId` function that returns one.
-### `fields`: `Object[]`
+#### `fields`: `Object[]`
The fields describe the visible items for each record in the dataset.
@@ -140,7 +145,7 @@ Each field is an object with the following properties:
- `operators`: the list of [operators](#operators) supported by the field.
- `isPrimary`: whether it is a primary filter. 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.
-### `view`: `object`
+#### `view`: `object`
The view object configures how the dataset is visible to the user.
@@ -183,7 +188,24 @@ Properties:
- `fields`: the `id` of the fields 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`
+##### Filter operators
+
+Allowed operators:
+
+| Operator | Selection | Description | Example |
+| ---------- | -------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
+| `is` | Single item | `EQUAL TO`. The item's field is equal to a single value. | Author is Admin |
+| `isNot` | Single item | `NOT EQUAL TO`. The item's field is not equal to a single value. | Author is not Admin |
+| `isAny` | Multiple items | `OR`. The item's field is present in a list of values. | Author is any: Admin, Editor |
+| `isNone` | Multiple items | `NOT OR`. The item's field is not present in a list of values. | Author is none: Admin, Editor |
+| `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.
+
+> The legacy operators `in` and `notIn` have been deprecated and will be removed soon. In the meantime, they work as `is` and `isNot` operators, respectively.
+
+##### Properties of `layout`
| Properties of `layout` | Table | Grid | List |
| --------------------------------------------------------------------------------------------------------------- | ----- | ---- | ---- |
@@ -194,7 +216,36 @@ Properties:
| `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. | ✓ | | |
-### `onChangeView`: `function`
+##### 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',
+ }
+ ]
+ }
+}
+```
+
+#### `onChangeView`: `function`
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.
@@ -259,7 +310,7 @@ function MyCustomPageTable() {
}
```
-### `actions`: `Object[]`
+#### `actions`: `Object[]`
Collection of operations that can be performed upon each record.
@@ -277,28 +328,28 @@ Each action is an object with the following properties:
- `supportsBulk`: Whether the action can be used as a bulk action. False by default.
- `disabled`: Whether the action is disabled. False by default.
-### `paginationInfo`: `Object`
+#### `paginationInfo`: `Object`
- `totalItems`: the total number of items in the datasets.
- `totalPages`: the total number of pages, taking into account the total items in the dataset and the number of items per page provided by the user.
-### `search`: `boolean`
+#### `search`: `boolean`
Whether the search input is enabled. `true` by default.
-### `searchLabel`: `string`
+#### `searchLabel`: `string`
What text to show in the search input. "Search" by default.
-### `getItemId`: `function`
+#### `getItemId`: `function`
Function that receives an item and returns an unique identifier for it. By default, it uses the `id` of the item as unique identifier. If it's not, the consumer should provide their own.
-### `isLoading`: `boolean`
+#### `isLoading`: `boolean`
Whether the data is loading. `false` by default.
-### `defaultLayouts`: `Record< string, view >`
+#### `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.
@@ -316,67 +367,45 @@ const defaultLayouts = {
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 [here](#properties-of-layout) the full list of properties available for each layout's configuration
-### `onChangeSelection`: `function`
+#### `onChangeSelection`: `function`
Callback that signals the user selected one of more items, and takes them as parameter. So far, only the `list` view implements it.
-## Types
-
-### Layouts
-
-- `table`: the view uses a table layout.
-- `grid`: the view uses a grid layout.
-- `list`: the view uses a list layout.
-
-### Fields
-
-> The `enumeration` type was removed as it was deemed redundant with the field.elements metadata. New types will be introduced soon.
+## `DataForm`
-## Combining fields
+### Usage
-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.
+```jsx
+const Example = () => {
+ // Declare data, fields, etc.
-Additionally, they need to provide:
+ return (
+
+ )
+}
+```
-- `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:
+### Props
-```js
-{
- fields: [ 'site', 'status' ],
- layout: {
- combinedFields: [
- {
- id: 'site',
- label: 'Site',
- children: [ 'title', 'description' ],
- direction: 'vertical',
- }
- ]
- }
-}
-```
+#### `data`: `Object[]`
-### Operators
+Same as `data` property of `DataViews`.
-Allowed operators:
+#### `fields`: `Object[]`
-| Operator | Selection | Description | Example |
-| ---------- | -------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
-| `is` | Single item | `EQUAL TO`. The item's field is equal to a single value. | Author is Admin |
-| `isNot` | Single item | `NOT EQUAL TO`. The item's field is not equal to a single value. | Author is not Admin |
-| `isAny` | Multiple items | `OR`. The item's field is present in a list of values. | Author is any: Admin, Editor |
-| `isNone` | Multiple items | `NOT OR`. The item's field is not present in a list of values. | Author is none: Admin, Editor |
-| `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 |
+Same as `fields` property of `DataViews`.
-`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.
+#### `form`: `Object[]`
-> The legacy operators `in` and `notIn` have been deprecated and will be removed soon. In the meantime, they work as `is` and `isNot` operators, respectively.
+- `type`: either `regular` or `panel`.
+- `fields`: a list of fields ids that should be rendered.
## Contributing to this package