DataViews: update docs

packages/dataviews/README.md

@@ -12,85 +12,147 @@ npm install @wordpress/dataviews --save
 
 ## Usage
 
-```js
-<DataViews
-	data={ data }
-	paginationInfo={ { totalItems, totalPages } }
-	view={ view }
-	onChangeView={ onChangeView }
-	fields={ fields }
-	actions={ [ trashPostAction ] }
-	search={ false }
-	searchLabel="Filter list"
-	getItemId={ ( item ) => item.id }
-	isLoading={ isLoadingData }
-	supportedLayouts={ [ 'table' ] }
-	deferredRendering={ true }
-	onSelectionChange={ ( items ) => { /* ... */ } }
-/>
+```jsx
+const Example = () => {
+
+	// Declare data, fields, etc.
+
+	return (
+		<DataViews
+			data={ data }
+			fields={ fields }
+			view={ view }
+			onChangeView={ onChangeView }
+			actions={ actions }
+			paginationInfo={ paginationInfo }
+		/>
+	);
+}
 ```
 
-## Data
+## Properties
+
+### `data`: `Object[]`
 
 The dataset to work with, represented as a one-dimensional array.
 
 Example:
 
 ```js
-[
-	{ id: 1, title: "Title", ... },
-	{ ... }
+const data = [
+	{
+		id: 1,
+		title: "Title",
+		author: "Admin",
+		date: "2012-04-23T18:25:43.511Z"
+	},
+	{ /* ... */ }
 ]
 ```
 
-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. See "Other props" section.
+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.
 
-## Pagination Info
+### `fields`: `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.
+The fields describe the visible items for each record in the dataset.
 
-## View
+Example:
+
+```js
+const fields = [
+	{
+		id: 'title',
+		header: 'Title',
+		getValue: ({ item }) => item.title,
+		enableHiding: false,
+	},
+	{
+		id: 'date',
+		header: 'Date',
+		getValue: ( { item } ) => item.date,
+		render: ( { item } ) => {
+			return (
+				<time>{ getFormattedDate( item.date ) }</time>
+			);
+		}
+	},
+	{
+		id: 'author',
+		header: __( 'Author' ),
+		getValue: ( { item } ) => item.author,
+		render: ( { item } ) => {
+			return (
+				<a href="...">{ item.author }</a>
+			);
+		},
+		type: 'enumeration',
+		elements: [
+			{ value: 1, label: 'Admin' }
+			{ value: 2, label: 'User' }
+		]
+		enableSorting: false
+	}
+]
+```
+
+Each field is an object with the following properties:
+
+-   `id`: identifier for the field. Unique.
+-   `header`: the field's name to be shown in the UI.
+-   `getValue`: function that returns the value of the field.
+-   `render`: function that renders the field. Optional, `getValue` will be used if `render` is not defined.
+-   `elements`: the set of valid values for the field's value.
+-   `type`: the type of the field. Used to generate the proper filters. Only `enumeration` available at the moment. See "Field types".
+-   `enableSorting`: whether the data can be sorted by the given field. True by default.
+-   `enableHiding`: whether the field can be hidden. True by default.
+-   `filterBy`: configuration for the filters.
+    - `operators`: the list of 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`
 
 The view object configures how the dataset is visible to the user.
 
 Example:
 
 ```js
-{
+const view = {
 	type: 'table',
-	perPage: 5,
-	page: 1,
-	sort: {
-		field: 'date',
-		direction: 'desc',
-	},
 	search: '',
 	filters: [
 		{ field: 'author', operator: 'in', value: 2 },
 		{ field: 'status', operator: 'in', value: 'publish,draft' }
 	],
+	page: 1,
+	perPage: 5,
+	sort: {
+		field: 'date',
+		direction: 'desc',
+	},
 	hiddenFields: [ 'date', 'featured-image' ],
 	layout: {},
 }
 ```
 
--   `type`: view type, one of `table`, `grid`, `list`. See "View types".
--   `perPage`: number of records to show per page.
--   `page`: the page that is visible.
--   `sort.field`: field used for sorting the dataset.
--   `sort.direction`: the direction to use for sorting, one of `asc` or `desc`.
+Properties:
+
+-   `type`: view type, one of `table`, `grid`, `list`. See "Layout types".
 -   `search`: the text search applied to the dataset.
 -   `filters`: the filters applied to the dataset. Each item describes:
     -   `field`: which field this filter is bound to.
     -   `operator`: which type of filter it is. One of `in`, `notIn`. See "Operator types".
     -   `value`: the actual value selected by the user.
+-   `perPage`: number of records to show per page.
+-   `page`: the page that is visible.
+-   `sort`:
+	- `field`: the field used for sorting the dataset.
+	- `direction`: the direction to use for sorting, one of `asc` or `desc`.
 -   `hiddenFields`: the `id` of the fields that are hidden in the UI.
 -   `layout`: config that is specific to a particular layout type.
     -   `mediaField`: used by the `grid` and `list` layouts. The `id` of the field to be used for rendering each card's media.
-    -   `primaryField`: used by the `grid` and `list` layouts. The `id` of the field to be highlighted in each card/list item.
+    -   `primaryField`: used by the `table`, `grid` and `list` layouts. The `id` of the field to be highlighted in each row/card/item.
 
-### onChangeView: syncing view and data
+### `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.
 
@@ -147,65 +209,17 @@ function MyCustomPageTable() {
 			data={ records }
 			view={ view }
 			onChangeView={ setView }
-			"..."
+			// ...
 		/>
 	);
 }
 ```
 
-## Fields
-
-The fields describe the visible items for each record in the dataset.
-
-Example:
-
-```js
-[
-	{
-		id: 'date',
-		header: __( 'Date' ),
-		getValue: ( { item } ) => item.date,
-		render: ( { item } ) => {
-			return (
-				<time>{ getFormattedDate( item.date ) }</time>
-			);
-		},
-		enableHiding: false
-	},
-	{
-		id: 'author',
-		header: __( 'Author' ),
-		getValue: ( { item } ) => item.author,
-		render: ( { item } ) => {
-			return (
-				<a href="...">{ item.author }</a>
-			);
-		},
-		type: 'enumeration',
-		elements: [
-			{ value: 1, label: 'Admin' }
-			{ value: 2, label: 'User' }
-		]
-		enableSorting: false
-	}
-]
-```
-
--   `id`: identifier for the field. Unique.
--   `header`: the field's name to be shown in the UI.
--   `getValue`: function that returns the value of the field.
--   `render`: function that renders the field.
--   `elements`: the set of valid values for the field's value.
--   `type`: the type of the field. Used to generate the proper filters. Only `enumeration` available at the moment. See "Field types".
--   `enableSorting`: whether the data can be sorted by the given field. True by default.
--   `enableHiding`: whether the field can be hidden. True by default.
--   `filterBy`: configuration for the filters.
-    - `operators`: the list of 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.
+### `actions`: `Object[]`
 
-## Actions
+Collection of operations that can be performed upon each record.
 
-Array of operations that can be performed upon each record. Each action is an object with the following properties:
+Each action is an object with the following properties:
 
 -   `id`: string, required. Unique identifier of the action. For example, `move-to-trash`.
 -   `label`: string, required. User facing description of the action. For example, `Move to Trash`.
@@ -217,28 +231,59 @@ Array of operations that can be performed upon each record. Each action is an ob
 -   `RenderModal`: ReactElement, optional. If an action requires that some UI be rendered in a modal, it can provide a component which takes as props the record as `item` and a `closeModal` 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.
 
+### `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`
+
+Whether the search input is enabled. `true` by default.
+
+### `searchLabel`: `string`
+
+What text to show in the search input. "Search" by default.
+
+### `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`
+
+Whether the data is loading. `false` by default.
+
+### `supportedLayouts`: `String[]`
+
+Array of layouts supported. By default, all are: `table`, `grid`, `list`.
+
+### `deferredRendering`: `boolean`
+
+Whether the items should be rendered asynchronously. Useful when there's a field that takes a lot of time (e.g.: previews). `false` by default.
+
+### `onSelectionChange`: `function`
+
+Callback that signals the user selected one of more items, and takes them as parameter. So far, only the `list` view implements it.
+
+### `onDetailsChange`: `function`
+
+Callback that signals the user triggered the details for one of more items, and takes them as paremeter. So far, only the `list` view implements it.
+
 ## Types
 
-- Layout types:
-    - `table`: the view uses a table layout.
-    - `grid`: the view uses a grid layout.
-    - `list`: the view uses a list layout.
-- Field types:
-    - `enumeration`: the field value should be taken and can be filtered from a closed list of elements.
-- Operator types:
-    - `in`: operator to be used in filters for fields of type `enumeration`.
-    - `notIn`: operator to be used in filters for fields of type `enumeration`.
-
-## Other properties
-
-- `search`: whether the search input is enabled. `true` by default.
-- `searchLabel`: what text to show in the search input. "Filter list" by default.
-- `getItemId`: 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`: whether the data is loading. `false` by default.
-- `supportedLayouts`: array of layouts supported. By default, all are: `table`, `grid`, `list`.
-- `deferredRendering`: whether the items should be rendered asynchronously. Useful when there's a field that takes a lot of time (e.g.: previews). `false` by default.
-- `onSelectionChange`: callback that signals the user selected one of more items, and takes them as parameter. So far, only the `list` view implements it.
-- `onDetailsChange`: callback that signals the user triggered the details for one of more items, and takes them as paremeter. So far, only the `list` view implements it.
+### Layouts
+
+- `table`: the view uses a table layout.
+- `grid`: the view uses a grid layout.
+- `list`: the view uses a list layout.
+
+### Fields
+
+- `enumeration`: the field value should be taken and can be filtered from a closed list of elements.
+
+### Operators
+
+- `in`: operator to be used in filters for fields of type `enumeration`.
+- `notIn`: operator to be used in filters for fields of type `enumeration`.
 
 ## Contributing to this package