Introduce <FilterLiveForm>

docs/FilterList.md

@@ -279,3 +279,96 @@ The children of `<FilterList>` must be a list of `<FilterListItem>` components.
 | `isSelected` | Optional | function | | A function that receives the item value and the currently applied filters. It must return a boolean. |
 | `toggleFilter` | Optional | function | | A function that receives the item value and the currently applied filters. It is called when user toggles a filter and must return the new filters to apply. |
 
+## Using Inputs
+
+If you want to add a simple text input to the sidebar, you can use the [`<FilterLiveSearch>`](./FilterLiveSearch.md) component alongside `<FilterList>` in the `<List>` sidebar. It will render a simple text input, which will filter the list based on the value entered by the user.
+
+{% raw %}
+```jsx
+import { FilterLiveSearch, FilterList, FilterListItem } from 'react-admin';
+import { Card, CardContent } from '@mui/material';
+import MailIcon from '@mui/icons-material/MailOutline';
+
+export const PostFilterSidebar = () => (
+    <Card sx={{ order: -1, mr: 2, mt: 6, width: 250, height: 'fit-content' }}>
+        <CardContent>
+            <FilterLiveSearch source="q" label="Search" />
+            <FilterList label="Subscribed to newsletter" icon={<MailIcon />}>
+                <FilterListItem label="Yes" value={{ has_newsletter: true }} />
+                <FilterListItem label="No" value={{ has_newsletter: false }} />
+            </FilterList>
+        </CardContent>
+    </Card>
+);
+```
+{% endraw %}
+
+If you want to use other type of inputs, such as a `<ReferenceInput>`, you can use the [`<FilterLiveForm>`](./FilterLiveForm.md) component to create a form that automatically updates the filters when the user changes the value of an input.
+
+{% raw %}
+```tsx
+import * as React from 'react';
+import CategoryIcon from '@mui/icons-material/LocalOffer';
+import Person2Icon from '@mui/icons-material/Person2';
+import TitleIcon from '@mui/icons-material/Title';
+import { Card, CardContent } from '@mui/material';
+import {
+    AutocompleteInput,
+    FilterLiveForm,
+    Datagrid,
+    FilterList,
+    FilterListItem,
+    FilterListSection,
+    List,
+    ReferenceField,
+    ReferenceInput,
+    TextField,
+    TextInput,
+} from 'react-admin';
+
+const BookListAside = () => (
+    <Card sx={{ order: -1, mr: 2, mt: 6, width: 250, height: 'fit-content' }}>
+        <CardContent>
+            <FilterList label="Century" icon={<CategoryIcon />}>
+                <FilterListItem
+                    label="21st"
+                    value={{ year_gte: 2000, year_lte: undefined }}
+                />
+                <FilterListItem
+                    label="20th"
+                    value={{ year_gte: 1900, year_lte: 1999 }}
+                />
+                <FilterListItem
+                    label="19th"
+                    value={{ year_gte: 1800, year_lte: 1899 }}
+                />
+            </FilterList>
+            <FilterListSection label="Title" icon={<TitleIcon />}>
+                <FilterLiveForm>
+                    <TextInput source="title" resettable helperText={false} />
+                </FilterLiveForm>
+            </FilterListSection>
+            <FilterListSection label="Author" icon={<Person2Icon />}>
+                <FilterLiveForm>
+                    <ReferenceInput source="authorId" reference="authors">
+                        <AutocompleteInput helperText={false} />
+                    </ReferenceInput>
+                </FilterLiveForm>
+            </FilterListSection>
+        </CardContent>
+    </Card>
+);
+
+export const BookList = () => (
+    <List aside={<BookListAside />}>
+        <Datagrid>
+            {/* ... */}
+        </Datagrid>
+    </List>
+);
+```
+{% endraw %}
+
+![FilterLiveForm](./img/FilterLiveForm.png)
+
+Check out the [`<FilterLiveForm>` documentation](./FilterLiveForm.md) for more information.

docs/FilterLiveForm.md

@@ -0,0 +1,160 @@
+---
+layout: default
+title: "FilterLiveForm"
+---
+
+# `<FilterLiveForm>`
+
+This component offers a convenient way to create a form that automatically updates the filters when the user changes its child input values.
+
+It fits nicely alongside a [`<FilterList>`](./FilterList.md) component, but you can also use it at other places to create your own filter UI.
+
+<video controls autoplay playsinline muted loop>
+  <source src="./img/FilterLiveForm.mp4" type="video/mp4"/>
+  Your browser does not support the video tag.
+</video>
+
+## Usage
+
+Use `<FilterLiveForm>` inside a component that provides a [`ListContext`](./useListContext.md), such as [`<List>`](./List.md). Use any React Admin [input component](./Inputs.md) as its children.
+
+Here is an example showing how you can use `<FilterLiveForm>` in a sidebar for the `<List>` view, alongside a [`<FilterList>`](./FilterList.md):
+
+{% raw %}
+```tsx
+import * as React from 'react';
+import CategoryIcon from '@mui/icons-material/LocalOffer';
+import Person2Icon from '@mui/icons-material/Person2';
+import TitleIcon from '@mui/icons-material/Title';
+import { Card, CardContent } from '@mui/material';
+import {
+    AutocompleteInput,
+    FilterLiveForm,
+    Datagrid,
+    FilterList,
+    FilterListItem,
+    FilterListSection,
+    List,
+    ReferenceField,
+    ReferenceInput,
+    TextField,
+    TextInput,
+} from 'react-admin';
+
+const BookListAside = () => (
+    <Card sx={{ order: -1, mr: 2, mt: 6, width: 250, height: 'fit-content' }}>
+        <CardContent>
+            <FilterList label="Century" icon={<CategoryIcon />}>
+                <FilterListItem
+                    label="21st"
+                    value={{ year_gte: 2000, year_lte: undefined }}
+                />
+                <FilterListItem
+                    label="20th"
+                    value={{ year_gte: 1900, year_lte: 1999 }}
+                />
+                <FilterListItem
+                    label="19th"
+                    value={{ year_gte: 1800, year_lte: 1899 }}
+                />
+            </FilterList>
+            <FilterListSection label="Title" icon={<TitleIcon />}>
+                <FilterLiveForm>
+                    <TextInput source="title" resettable helperText={false} />
+                </FilterLiveForm>
+            </FilterListSection>
+            <FilterListSection label="Author" icon={<Person2Icon />}>
+                <FilterLiveForm>
+                    <ReferenceInput source="authorId" reference="authors">
+                        <AutocompleteInput helperText={false} />
+                    </ReferenceInput>
+                </FilterLiveForm>
+            </FilterListSection>
+        </CardContent>
+    </Card>
+);
+
+export const BookList = () => (
+    <List aside={<BookListAside />}>
+        <Datagrid>
+            <TextField source="title" />
+            <ReferenceField source="authorId" reference="authors" />
+            <TextField source="year" />
+        </Datagrid>
+    </List>
+);
+```
+{% endraw %}
+
+**Tip:** This example leverages `<FilterListSection>`, the wrapper used internally by `<FilterList>`, in order to obtain a consistent look and feel for the filters.
+
+![FilterLiveForm](./img/FilterLiveForm.png)
+
+**Tip:** `<FilterLiveForm>` accepts multiple children, but you can also use several `<FilterLiveForm>` components in the same filter UI, just like we did above.
+
+**Tip:** For simple cases where you only need a text input, you can use the [`<FilterLiveSearch>`](./FilterLiveSearch.md) component, which combines that logic in a single component.
+
+## Props
+
+Here are all the props you can set on the `<FilterLiveForm>` component:
+
+| Prop            | Required | Type                | Default              | Description                                                              |
+| --------------- | -------- | ------------------- | -------------------- | ------------------------------------------------------------------------ |
+| `children`      | Required | `ReactNode`         | -                    | The children of the filter form (usually inputs)                         |
+| `formComponent` | Optional | React Component     | Native HTML `<form>` | A React Component used to render the form                                |
+| `debounce`      | Optional | `number` or `false` | 500                  | The debounce delay to set the filters (pass `false` to disable debounce) |
+| `validate`      | Optional | `function`          | -                    | A function to validate the form values                                   |
+
+Additional props are passed to `react-hook-form`'s [`useForm` hook](https://react-hook-form.com/docs/useform).
+
+## `children`
+
+`<FilterLiveForm>` accepts any children. It simply provides the required contexts for the inputs to work as filters.
+
+```tsx
+<FilterLiveForm>
+    <TextInput source="title" resettable helperText={false} />
+    <TextInput source="author" resettable helperText={false} />
+</FilterLiveForm>
+```
+
+## `debounce`
+
+You can use the `debounce` prop to customize the delay before the filters are applied. The default value is `500` milliseconds.
+
+```tsx
+<FilterLiveForm debounce={1000}>
+    <TextInput source="title" resettable helperText={false} />
+    <TextInput source="author" resettable helperText={false} />
+</FilterLiveForm>
+```
+
+You can also disable the debounce by setting the `debounce` prop to `false`.
+
+```tsx
+<FilterLiveForm debounce={false}>
+    <TextInput source="title" resettable helperText={false} />
+    <TextInput source="author" resettable helperText={false} />
+</FilterLiveForm>
+```
+
+## `validate`
+
+Just like for [`<Form>`](./Form.md), you can provide a `validate` function to validate the form values.
+
+```tsx
+const validateFilters = values => {
+    const errors: any = {};
+    if (!values.author) {
+        errors.author = 'The author is required';
+    }
+    return errors;
+};
+
+const GlobalValidation = () => (
+    <FilterLiveForm validate={validateFilters}>
+        <TextInput source="title" resettable helperText={false} />
+        <TextInput source="author" resettable helperText={false} />
+    </FilterLiveForm>
+);
+```

docs/FilterLiveSearch.md

@@ -12,7 +12,7 @@ title: "The FilterLiveSearch Component"
 </video>
 
 
-The filter sidebar is not a form. Therefore, if your users need to enter complex filters, you'll have to recreate a filter form using react-hook-form (see the [Building a custom filter](./FilteringTutorial.md#building-a-custom-filter) for an example). However, if you only need one text input with a filter-as-you-type behavior, you'll find the `<FilterLiveSearch>` component convenient.
+The filter sidebar is not a form. Therefore, if your users need to enter complex filters, you'll have to recreate a filter form. This can be done thanks to the [`<FilterLiveForm>`](./FilterLiveForm.md) component. However, if you only need one text input with a filter-as-you-type behavior, you'll find the `<FilterLiveSearch>` component even more convenient.
 
 It outputs a form containing a single `<TextInput>`, which modifies the page filter on change. That's usually what users expect for a full-text filter.
 
@@ -55,4 +55,76 @@ export const CustomerList = () => (
 | `source` | Optional | `string` | 'q' | The field to filter on. |
 | `variant` | Optional | `string` | 'standard' | The variant of the search input. Can be one of 'standard', 'outlined', or 'filled'. |
 
-Additional props are passed down to [the Material UI `<TextField>` component](https://mui.com/material-ui/api/text-field/).
+Additional props are passed down to [the Material UI `<TextField>` component](https://mui.com/material-ui/api/text-field/).
+
+## Using Your Own Input
+
+If the text input provided by `<FilterLiveSearch>` is not enough, and you'd like to use your own input component, you can use the `<FilterLiveForm>` component to create a form that automatically updates the filters when the user changes the input value.
+
+{% raw %}
+```tsx
+import * as React from 'react';
+import CategoryIcon from '@mui/icons-material/LocalOffer';
+import Person2Icon from '@mui/icons-material/Person2';
+import TitleIcon from '@mui/icons-material/Title';
+import { Card, CardContent } from '@mui/material';
+import {
+    AutocompleteInput,
+    FilterLiveForm,
+    Datagrid,
+    FilterList,
+    FilterListItem,
+    FilterListSection,
+    List,
+    ReferenceField,
+    ReferenceInput,
+    TextField,
+    TextInput,
+} from 'react-admin';
+
+const BookListAside = () => (
+    <Card sx={{ order: -1, mr: 2, mt: 6, width: 250, height: 'fit-content' }}>
+        <CardContent>
+            <FilterList label="Century" icon={<CategoryIcon />}>
+                <FilterListItem
+                    label="21st"
+                    value={{ year_gte: 2000, year_lte: undefined }}
+                />
+                <FilterListItem
+                    label="20th"
+                    value={{ year_gte: 1900, year_lte: 1999 }}
+                />
+                <FilterListItem
+                    label="19th"
+                    value={{ year_gte: 1800, year_lte: 1899 }}
+                />
+            </FilterList>
+            <FilterListSection label="Title" icon={<TitleIcon />}>
+                <FilterLiveForm>
+                    <TextInput source="title" resettable helperText={false} />
+                </FilterLiveForm>
+            </FilterListSection>
+            <FilterListSection label="Author" icon={<Person2Icon />}>
+                <FilterLiveForm>
+                    <ReferenceInput source="authorId" reference="authors">
+                        <AutocompleteInput helperText={false} />
+                    </ReferenceInput>
+                </FilterLiveForm>
+            </FilterListSection>
+        </CardContent>
+    </Card>
+);
+
+export const BookList = () => (
+    <List aside={<BookListAside />}>
+        <Datagrid>
+            {/* ... */}
+        </Datagrid>
+    </List>
+);
+```
+{% endraw %}
+
+![FilterLiveForm](./img/FilterLiveForm.png)
+
+Check out the [`<FilterLiveForm>` documentation](./FilterLiveForm.md) for more information.

docs/FilteringTutorial.md

@@ -522,7 +522,48 @@ Normally, `showFilter()` adds one input to the `displayedFilters` list. As the f
 
 ### Custom Filter Form
 
-Next is the filter form component, displayed only when the "main" filter is displayed (i.e. when a user has clicked the filter button). The form inputs appear directly in the form, and the form submission triggers the `setFilters()` callback passed as parameter. We'll use `react-hook-form` to handle the form state:
+If you need to build a custom filter form, you can use the [`<FilterLiveForm>`](./FilterLiveForm.md) component to create a form that automatically updates the filters when the user changes the input value.
+
+{% raw %}
+```jsx
+import * as React from 'react';
+import { Box, InputAdornment } from '@mui/material';
+import SearchIcon from '@mui/icons-material/Search';
+import { FilterLiveForm, TextInput, NullableBooleanInput } from 'react-admin';
+
+const PostFilterForm = () => (
+    <FilterLiveForm>
+        <Box display="flex" alignItems="flex-end" mb={1}>
+            <Box component="span" mr={2}>
+                {/* Full-text search filter. We don't use <SearchFilter> to force a large form input */}
+                <TextInput
+                    resettable
+                    helperText={false}
+                    source="q"
+                    label="Search"
+                    InputProps={{
+                        endAdornment: (
+                            <InputAdornment>
+                                <SearchIcon color="disabled" />
+                            </InputAdornment>
+                        )
+                    }}
+                />
+            </Box>
+            <Box component="span" mr={2}>
+                {/* Commentable filter */}
+                <NullableBooleanInput
+                    helperText={false}
+                    source="commentable"
+                />
+            </Box>
+        </Box>
+    </FilterLiveForm>
+);
+```
+{% endraw %}
+
+If, instead, you want to control the form submission yourself, you can use the `useForm` hook from `react-hook-form`, and leverage the [filter callbacks](#filter-callbacks) from the `ListContext`:
 
 {% raw %}
 ```jsx