useList - documentation & more tests

docs/List.md

@@ -2007,6 +2007,38 @@ As you can see, the controller part of the List view is handled by a hook called
 
 **Tip**: If your custom List view doesn't use a `ListContextProvider`, you can't use `<Datagrid>`, `<SimpleList>`, `<Pagination>`, etc. All these components rely on the `ListContext`.
 
+## `useList`
+
+The `useList` hook allows to apply the list features such as filtering, sorting and paginating on an array of records you already have.
+
+Thanks to it, you can display your data inside a [`<Datagrid>`](#the-datagrid-component), a [`<SimpleList>`](#the-simplelist-component) or an [`<EditableDatagrid>`](#the-editabledatagrid-component). For example:
+
+```jsx
+const data = [
+    { id: 1, name: 'Arnold' },
+    { id: 2, name: 'Sylvester' },
+    { id: 3, name: 'Jean-Claude' },
+]
+const ids = [1, 2, 3];
+
+const MyComponent = () => {
+    const listContext = useList({
+        data,
+        ids,
+        basePath: '/resource';
+        resource: 'resource';
+    });
+    return (
+        <ListContextProvider value={listContext}>
+            <Datagrid>
+                <TextField source="id" />
+                <TextField source="name" />
+            </Datagrid>
+        </ListContextProvider>
+    );
+};
+```
+
 ## The `<Datagrid>` component
 
 ![The `<Datagrid>` component](./img/tutorial_post_list_less_columns.png)

packages/ra-core/src/controller/useList.spec.tsx

@@ -1,16 +1,23 @@
 import * as React from 'react';
+import { ReactNode } from 'react';
 import expect from 'expect';
 
 import { useList, UseListOptions, UseListValue } from './useList';
-import { render, waitFor } from '@testing-library/react';
+import { fireEvent, render, waitFor } from '@testing-library/react';
+import ListContextProvider from './ListContextProvider';
+import useListContext from './useListContext';
 
 const UseList = ({
+    children,
     callback,
     ...props
-}: UseListOptions & { callback: (value: UseListValue) => void }) => {
+}: UseListOptions & {
+    children?: ReactNode;
+    callback: (value: UseListValue) => void;
+}) => {
     const value = useList(props);
     callback(value);
-    return null;
+    return <ListContextProvider value={value}>{children}</ListContextProvider>;
 };
 
 describe('<useList />', () => {
@@ -96,15 +103,27 @@ describe('<useList />', () => {
         ];
         const ids = [1, 2];
 
-        render(
+        const SortButton = () => {
+            const listContext = useListContext();
+
+            return (
+                <button onClick={() => listContext.setSort('title', 'ASC')}>
+                    Sort by title ASC
+                </button>
+            );
+        };
+
+        const { getByText } = render(
             <UseList
                 data={data}
                 ids={ids}
                 loaded
                 loading
                 sort={{ field: 'title', order: 'DESC' }}
                 callback={callback}
-            />
+            >
+                <SortButton />
+            </UseList>
         );
 
         await waitFor(() => {
@@ -122,6 +141,23 @@ describe('<useList />', () => {
                 })
             );
         });
+
+        fireEvent.click(getByText('Sort by title ASC'));
+        await waitFor(() => {
+            expect(callback).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    currentSort: { field: 'title', order: 'ASC' },
+                    loaded: true,
+                    loading: true,
+                    data: {
+                        1: { id: 1, title: 'hello' },
+                        2: { id: 2, title: 'world' },
+                    },
+                    ids: [1, 2],
+                    error: undefined,
+                })
+            );
+        });
     });
 
     it('should apply pagination correctly', async () => {

packages/ra-core/src/controller/useList.ts

@@ -29,8 +29,8 @@ import { ListControllerProps } from '.';
  *
  * const MyComponent = () => {
  *     const listContext = useList({
- *         initialData: data,
- *         initialIds: ids,
+ *         data,
+ *         ids,
  *         basePath: '/resource';
  *         resource: 'resource';
  *     });