Add SelectColumns and DatagridConfigurable

docs/Datagrid.md

@@ -695,6 +695,7 @@ The `<Datagrid>` component accepts the usual `className` prop. You can also over
 
 | Rule name                      | Description                                      |
 | ------------------------------ |--------------------------------------------------|
+| `& .RaDatagrid-root`           | Applied to the root div element                  |
 | `& .RaDatagrid-tableWrapper`   | Applied to the div that wraps table element      |
 | `& .RaDatagrid-table`          | Applied to the table element                     |
 | `& .RaDatagrid-thead`          | Applied to the table header                      |
@@ -797,6 +798,105 @@ const PostList = () => (
 ```
 {% endraw %}
 
+## Showing / Hiding Columns
+
+The [`<SelectColumnsButton>`](./SelectColumnsButton.md) lets users hide or show datagrid columns. 
+
+![SelectColumnsButton](./img/SelectColumnsButton.gif)
+
+```jsx
+import {
+    DatagridConfigurable,
+    List,
+    SelectColumnsButton,
+    TextField,
+    TopToolbar,
+} from "react-admin";
+
+const PostListActions = () => (
+    <TopToolbar>
+        <SelectColumnsButton />
+    </TopToolbar>
+);
+
+const PostList = () => (
+    <List actions={<PostListActions />}>
+        <DatagridConfigurable>
+            <TextField source="id" />
+            <TextField source="title" />
+            <TextField source="author" />
+            <TextField source="year" />
+        </DatagridConfigurable>
+    </List>
+);
+```
+
+`<SelectColumnsButton>` must be used in conjunction with `<DatagridConfigurable>`, the configurable version of `<Datagrid>`, described in the next section.
+
+## Configurable
+
+You can let end users customize the fields displayed in the `<Datagrid>` by using the `<DatagridConfigurable>` component instead.
+
+![DatagridConfigurable](./img/DatagridConfigurable.gif)
+
+```diff
+import {
+    List,
+-   Datagrid,
++   DatagridConfigurable,
+    TextField,
+} from 'react-admin';
+
+const PostList = () => (
+    <List>
+-       <Datagrid>
++       <DatagridConfigurable>
+            <TextField source="id" />
+            <TextField source="title" />
+            <TextField source="author" />
+            <TextField source="year" />
+-       </Datagrid>
++       </DatagridConfigurable>
+    </List>
+);
+```
+
+When users enter the configuration mode and select the `<Datagrid>`, they can show / hide datagrid columns. They can also use the [`<SelectColumnsButton>`](./SelectColumnsButton.md)
+
+By default, `<DatagridConfigurable>` renders all child fields. But you can also omit some of them by passing an `omit` prop containing an array of field sources:
+
+```jsx
+// by default, hide the id and author columns
+// users can choose to show them in configuration mode
+const PostList = () => (
+    <List>
+        <DatagridConfigurable omit={['id', 'author']}>
+            <TextField source="id" />
+            <TextField source="title" />
+            <TextField source="author" />
+            <TextField source="year" />
+        </DatagridConfigurable>
+    </List>
+);
+```
+
+If you render more than one `<DatagridConfigurable>` in the same page, you must pass a unique `preferenceKey` prop to each one:
+
+```jsx
+const PostList = () => (
+    <List>
+        <DatagridConfigurable preferenceKey="posts.datagrid">
+            <TextField source="id" />
+            <TextField source="title" />
+            <TextField source="author" />
+            <TextField source="year" />
+        </DatagridConfigurable>
+    </List>
+);
+```
+
+`<DatagridConfigurable>` accepts the same props as `<Datagrid>`.
+
 ## Customizing Column Sort
 
 ![Sort Column Header](./img/sort-column-header.gif)

docs/Reference.md

@@ -115,7 +115,7 @@ title: "Reference"
 * [`<Search>`](https://marmelab.com/ra-enterprise/modules/ra-search#the-search-component)<img class="icon" src="./img/premium.svg" />
 * [`<SearchInput>`](./FilteringTutorial.md#searchinput)
 * [`<SelectArrayInput>`](./SelectArrayInput.md)
-* [`<SelectColumnsButton>`](https://marmelab.com/ra-enterprise/modules/ra-preferences#selectcolumnsbutton-store-datagrid-columns-in-preferences)<img class="icon" src="./img/premium.svg" />
+* [`<SelectColumnsButton>`](./SelectColumnsButton.md)
 * [`<SelectField>`](./SelectField.md)
 * [`<SelectInput>`](./SelectInput.md)
 * [`<Show>`](./Show.md#show)

docs/SelectColumnsButton.md

@@ -0,0 +1,83 @@
+---
+layout: default
+title: "The SelectColumnsButton Component"
+---
+
+# `<SelectColumnsButton>`
+
+This button lets users show or hide columns in a Datagrid. It must be used in conjunction with [`<DatagridConfigurable>`](./Datagrid.md#configurable).
+
+![SelectColumnsButton](./img/SelectColumnsButton.gif)
+
+```jsx
+import {
+    DatagridConfigurable,
+    List,
+    SelectColumnsButton,
+    TextField,
+    TopToolbar,
+} from "react-admin";
+
+const PostListActions = () => (
+    <TopToolbar>
+        <SelectColumnsButton />
+    </TopToolbar>
+);
+
+const PostList = () => (
+    <List actions={<PostListActions />}>
+        <DatagridConfigurable>
+            <TextField source="id" />
+            <TextField source="title" />
+            <TextField source="author" />
+            <TextField source="year" />
+        </DatagridConfigurable>
+    </List>
+);
+```
+
+**Note**: `<SelectColumnsButton>` doesn't work with `<Datagrid>` - you must use `<DatagridConfigurable>` instead.
+
+If you want to add the `<SelectColumnsButton>` to the usual List Actions, use the following snippet:
+
+```jsx
+const ListActions = () => (
+    <TopToolbar>
+        <SelectColumnsButton />
+        <FilterButton />
+        <CreateButton />
+        <ExportButton />
+    </TopToolbar>
+);
+```
+
+## `preferenceKey`
+
+If you include `<SelectColumnsButton>` in a page that has more than one `<DatagridConfigurable>` (e.g. in a dasboard), you have to link the two components by giving them the same `preferenceKey`:
+
+```jsx
+const BookList = () => {
+    const { data, total, isLoading } = useGetList('books', {
+        pagination: { page: 1, perPage: 10 },
+        sort,
+    });
+    return (
+        <div>
+            <SelectColumnsButton preferenceKey="postList1" />
+            <DatagridConfigurable
+                preferenceKey="postList1"
+                data={data}
+                total={total}
+                isLoading={isLoading}
+                sort={sort}
+                bulkActionButtons={false}
+            >
+                <TextField source="id" />
+                <TextField source="title" />
+                <TextField source="author" />
+                <TextField source="year" />
+            </DatagridConfigurable>
+        </div>
+    );
+};
+```

docs/navigation.html

@@ -75,6 +75,7 @@
   <li {% if page.path == 'SavedQueriesList.md' %} class="active" {% endif %}><a class="nav-link" href="./SavedQueriesList.html"><code>&lt;SavedQueriesList&gt;</code></a></li>
   <li {% if page.path == 'Pagination.md' %} class="active" {% endif %}><a class="nav-link" href="./Pagination.html"><code>&lt;Pagination&gt;</code></a></li>
   <li {% if page.path == 'SortButton.md' %} class="active" {% endif %}><a class="nav-link" href="./SortButton.html"><code>&lt;SortButton&gt;</code></a></li>
+  <li {% if page.path == 'SelectColumnsButton.md' %} class="active" {% endif %}><a class="nav-link" href="./SelectColumnsButton.html"><code>&lt;SelectColumnsButton&gt;</code></a></li>
   <li {% if page.path == 'useList.md' %} class="active" {% endif %}><a class="nav-link" href="./useList.html"><code>useList</code></a></li>
   <li {% if page.path == 'useListContext.md' %} class="active" {% endif %}><a class="nav-link" href="./useListContext.html"><code>useListContext</code></a></li>
   <li {% if page.path == 'useListController.md' %} class="active" {% endif %}><a class="nav-link" href="./useListController.html"><code>useListController</code></a></li>

examples/demo/src/orders/OrderList.tsx

@@ -3,7 +3,7 @@ import { Fragment, useCallback } from 'react';
 import {
     AutocompleteInput,
     BooleanField,
-    Datagrid,
+    DatagridConfigurable,
     DateField,
     DateInput,
     List,
@@ -16,6 +16,10 @@ import {
     TextInput,
     useGetList,
     useListContext,
+    TopToolbar,
+    SelectColumnsButton,
+    FilterButton,
+    ExportButton,
 } from 'react-admin';
 import { useMediaQuery, Divider, Tabs, Tab, Theme } from '@mui/material';
 
@@ -25,12 +29,21 @@ import AddressField from '../visitors/AddressField';
 import MobileGrid from './MobileGrid';
 import { Customer } from '../types';
 
+const ListActions = () => (
+    <TopToolbar>
+        <SelectColumnsButton />
+        <FilterButton />
+        <ExportButton />
+    </TopToolbar>
+);
+
 const OrderList = () => (
     <List
         filterDefaultValues={{ status: 'ordered' }}
         sort={{ field: 'date', order: 'DESC' }}
         perPage={25}
         filters={orderFilters}
+        actions={<ListActions />}
     >
         <TabbedDatagrid />
     </List>
@@ -130,7 +143,10 @@ const TabbedDatagrid = () => {
             ) : (
                 <>
                     {filterValues.status === 'ordered' && (
-                        <Datagrid optimized rowClick="edit">
+                        <DatagridConfigurable
+                            rowClick="edit"
+                            omit={['total_ex_taxes', 'delivery_fees', 'taxes']}
+                        >
                             <DateField source="date" showTime />
                             <TextField source="reference" />
                             <CustomerReferenceField />
@@ -143,6 +159,27 @@ const TabbedDatagrid = () => {
                                 <AddressField />
                             </ReferenceField>
                             <NbItemsField />
+                            <NumberField
+                                source="total_ex_taxes"
+                                options={{
+                                    style: 'currency',
+                                    currency: 'USD',
+                                }}
+                            />
+                            <NumberField
+                                source="delivery_fees"
+                                options={{
+                                    style: 'currency',
+                                    currency: 'USD',
+                                }}
+                            />
+                            <NumberField
+                                source="taxes"
+                                options={{
+                                    style: 'currency',
+                                    currency: 'USD',
+                                }}
+                            />
                             <NumberField
                                 source="total"
                                 options={{
@@ -151,10 +188,13 @@ const TabbedDatagrid = () => {
                                 }}
                                 sx={{ fontWeight: 'bold' }}
                             />
-                        </Datagrid>
+                        </DatagridConfigurable>
                     )}
                     {filterValues.status === 'delivered' && (
-                        <Datagrid rowClick="edit">
+                        <DatagridConfigurable
+                            rowClick="edit"
+                            omit={['total_ex_taxes', 'delivery_fees', 'taxes']}
+                        >
                             <DateField source="date" showTime />
                             <TextField source="reference" />
                             <CustomerReferenceField />
@@ -167,6 +207,27 @@ const TabbedDatagrid = () => {
                                 <AddressField />
                             </ReferenceField>
                             <NbItemsField />
+                            <NumberField
+                                source="total_ex_taxes"
+                                options={{
+                                    style: 'currency',
+                                    currency: 'USD',
+                                }}
+                            />
+                            <NumberField
+                                source="delivery_fees"
+                                options={{
+                                    style: 'currency',
+                                    currency: 'USD',
+                                }}
+                            />
+                            <NumberField
+                                source="taxes"
+                                options={{
+                                    style: 'currency',
+                                    currency: 'USD',
+                                }}
+                            />
                             <NumberField
                                 source="total"
                                 options={{
@@ -179,10 +240,13 @@ const TabbedDatagrid = () => {
                                 source="returned"
                                 sx={{ mt: -0.5, mb: -0.5 }}
                             />
-                        </Datagrid>
+                        </DatagridConfigurable>
                     )}
                     {filterValues.status === 'cancelled' && (
-                        <Datagrid rowClick="edit">
+                        <DatagridConfigurable
+                            rowClick="edit"
+                            omit={['total_ex_taxes', 'delivery_fees', 'taxes']}
+                        >
                             <DateField source="date" showTime />
                             <TextField source="reference" />
                             <CustomerReferenceField />
@@ -195,6 +259,27 @@ const TabbedDatagrid = () => {
                                 <AddressField />
                             </ReferenceField>
                             <NbItemsField />
+                            <NumberField
+                                source="total_ex_taxes"
+                                options={{
+                                    style: 'currency',
+                                    currency: 'USD',
+                                }}
+                            />
+                            <NumberField
+                                source="delivery_fees"
+                                options={{
+                                    style: 'currency',
+                                    currency: 'USD',
+                                }}
+                            />
+                            <NumberField
+                                source="taxes"
+                                options={{
+                                    style: 'currency',
+                                    currency: 'USD',
+                                }}
+                            />
                             <NumberField
                                 source="total"
                                 options={{
@@ -203,11 +288,7 @@ const TabbedDatagrid = () => {
                                 }}
                                 sx={{ fontWeight: 'bold' }}
                             />
-                            <BooleanField
-                                source="returned"
-                                sx={{ mt: -0.5, mb: -0.5 }}
-                            />
-                        </Datagrid>
+                        </DatagridConfigurable>
                     )}
                 </>
             )}