Merge branch 'next' into marmelab/listRenderProp

Author: fzaninotto

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 5.10.0
+
+- Upgraded `@tanstack/react-query` to `5.83.0`. You might have duplicate versions if you already had it in your dependencies. Should you have an error mentioning the `QueryContext`, make sure you only have one version in your package manager lock file.
+
 ## 5.9.1
 
 * Fix `<Datagrid>` empty throws error when used in standalone mode ([#10812](https://github.com/marmelab/react-admin/pull/10812)) ([fzaninotto](https://github.com/fzaninotto))

docs/List.md

@@ -1202,6 +1202,42 @@ const ProductList = () => (
 )
 ```
 
+## Enabling Data Fetching Conditionally
+
+You might want to allow data to be fetched only when at least some filters have been set. You can leverage TanStack react-query `enabled` option for that. It accepts a function that receives the query as its only parameter. As react-admin always format the `queryKey` as `[ResourceName, DataProviderMethod, DataProviderParams]`, you can check that there is at least a filter in this function:
+
+{% raw %}
+```tsx
+export const PostList = () => (
+    <List
+        filters={postFilter}
+        queryOptions={{
+            enabled: query => {
+                const listParams = query.queryKey[2] as GetListParams;
+                return listParams.filter.q?.length > 2;
+            }
+        }}
+    >
+        <WithListContext
+            render={context =>
+                context.filterValues.q?.length > 2 ? (
+                    <CardContentInner>
+                        Type a search term to fetch data
+                    </CardContentInner>
+                ) : (
+                    <Datagrid>
+                        {/* your fields */}
+                    </Datagrid>
+                )
+            }
+        />
+    </List>
+)
+```
+{% endraw %}
+
+**Note**: Notice we display some custom UI when there is no filter. This is because otherwise, users would see the loading UI as Tanstack Query will set the `isPending` property of the underlying query to `true` if the query isn't enabled. 
+
 ## Accessing Extra Response Data
 
 If `dataProvider.getList()` returns additional metadata in the response under the `meta` key, you can access it in the list view using the `meta` property of the `ListContext`.

docs/ListBase.md

@@ -6,55 +6,81 @@ storybook_path: ra-core-controller-list-listbase--no-auth-provider
 
 # `<ListBase>`
 
-`<ListBase>` is a headless variant of [`<List>`](./List.md). It fetches a list of records from the data provider, puts it in a [`ListContext`](./useListContext.md), and renders its children. Use it to build a custom list layout.
+`<ListBase>` is a headless List page component. It fetches a list of records from the data provider, puts it in a [`ListContext`](./useListContext.md), and renders its children. Use it to build a custom list layout.
 
 Contrary to [`<List>`](./List.md), it does not render the page layout, so no title, no actions, no `<Card>`, and no pagination.
 
 `<ListBase>` relies on the [`useListController`](./useListController.md) hook.
 
 ## Usage
 
-You can use `ListBase` to create your own custom reusable List component, like this one:
+You can use `ListBase` to create your own custom List page component, like this one:
 
 ```jsx
 import { 
+    DataTable,
     ListBase,
-    Title,
     ListToolbar,
-    Pagination,
     DataTable,
+    Pagination,
+    Title,
 } from 'react-admin';
 import { Card } from '@mui/material';
 
-const MyList = ({ children, actions, filters, title, ...props }) => (
-    <ListBase {...props}>
-        <Title title={title}/>
+const PostList = () => (
+    <ListBase>
+        <Title title="Post List"/>
         <ListToolbar
-            filters={filters}
-            actions={actions}
+            filters={[
+                { source: 'q', label: 'Search', alwaysOn: true },
+                { source: 'published', label: 'Published', type: 'boolean' },
+            ]}
         />
         <Card>
-            {children}
+            <DataTable>
+                <DataTable.Col source="title" />
+                <DataTable.Col source="author" />
+                <DataTable.Col source="published_at" />
+            </DataTable>
         </Card>
         <Pagination />
     </ListBase>
 );
+```
 
+Alternatively, you can pass a `render` function prop instead of `children`. This function will receive the `ListContext` as argument.
+
+```jsx
 const PostList = () => (
-    <MyList title="Post List">
-        <DataTable>
-            ...
-        </DataTable>
-    </MyList>
+    <ListBase render={({ data, total, isPending, error }) => (
+        <Card>
+            <Title title="Post List" />
+            <ListToolbar
+                filters={[
+                    { source: 'q', label: 'Search', alwaysOn: true },
+                    { source: 'published', label: 'Published', type: 'boolean' },
+                ]}
+            />
+            <DataTable>
+                {data?.map(record => (
+                    <DataTable.Row key={record.id}>
+                        <DataTable.Col source="title" record={record} />
+                        <DataTable.Col source="author" record={record} />
+                        <DataTable.Col source="published_at" record={record} />
+                    </DataTable.Row>
+                ))}
+            </DataTable>
+            <Pagination total={total} />
+        </Card>
+    )} />
 );
 ```
 
-This custom List component has no aside component - it's up to you to add it in pure React.
-
 ## Props
 
-The `<ListBase>` component accepts the same props as [`useListController`](./useListController.md):
+The `<ListBase>` component accepts the following props:
 
+* `children`
 * [`debounce`](./List.md#debounce)
 * [`disableAuthentication`](./List.md#disableauthentication)
 * [`disableSyncWithLocation`](./List.md#disablesyncwithlocation)
@@ -63,11 +89,12 @@ The `<ListBase>` component accepts the same props as [`useListController`](./use
 * [`filterDefaultValues`](./List.md#filterdefaultvalues)
 * [`perPage`](./List.md#perpage)
 * [`queryOptions`](./List.md#queryoptions)
+* `render`
 * [`resource`](./List.md#resource)
 * [`sort`](./List.md#sort)
 
 In addition, `<ListBase>` renders its children components inside a `ListContext`. Check [the `<List children>` documentation](./List.md#children) for usage examples.
-Alternatively, you can pass a `render` function prop instead of `children`. This function will receive the `ListContext` as argument. 
+
 
 ## Security