# FilterPicker

`FilterPicker` is the default filter action for Applica list pages that define `filters` as an array.

It replaces the standard React-Admin `FilterButton` with a searchable popover. The filter form itself is still rendered by the list toolbar, so `alwaysOn` filters remain visible in the toolbar and optional filters are displayed when selected from the picker.

## Default Usage

No extra configuration is required when using the Applica `List` component with an array of filters:

```tsx
import { Datagrid, List, SearchInput, TextField, TextInput } from '@applica-software-guru/react-admin';

const postFilters = [
  <SearchInput key="q" source="q" alwaysOn />,
  <TextInput key="title" source="title" />,
  <TextInput key="author" source="author" />
];

export function PostList() {
  return (
    <List filters={postFilters}>
      <Datagrid>
        <TextField source="id" />
        <TextField source="title" />
      </Datagrid>
    </List>
  );
}
```

In this configuration:

- `alwaysOn` filters are rendered directly in the toolbar.
- Optional filters are listed in the `FilterPicker` popover.
- The popover includes search, selected-filter chips, saved queries and a remove-all action.

## Filter Groups

Optional filters can be grouped by adding a `filterGroup` prop to each filter element. Groups are rendered as section headers in the picker when more than one group is visible.

```tsx
const filters = [
  <SearchInput key="q" source="q" alwaysOn />,
  <TextInput key="status" source="status" filterGroup="standard" />,
  <TextInput key="control_temperature" source="control_temperature__like" filterGroup="controls" />,
  <TextInput key="characteristic_color" source="characteristic_color__like" filterGroup="characteristics" />
];

export function ItemList() {
  return <List filters={filters}>{/* ... */}</List>;
}
```

Default `List` actions pass the filters to `FilterPicker` automatically. When rendering `FilterPicker` manually, provide group labels with the `groups` prop:

```tsx
<FilterPicker
  filters={filters}
  groups={{
    standard: 'Standard filters',
    controls: 'Controls',
    characteristics: 'Characteristics'
  }}
/>
```

If a filter has no `filterGroup`, it is assigned to `defaultGroup`, which defaults to `standard`.

## Custom Actions

If a list defines custom actions, render `FilterPicker` explicitly and pass the same `filters` array:

```tsx
import { CreateButton, FilterPicker, TopToolbar } from '@applica-software-guru/react-admin';

function PostActions({ filters }) {
  return (
    <TopToolbar>
      <FilterPicker filters={filters} />
      <CreateButton />
    </TopToolbar>
  );
}

export function PostList() {
  const filters = [<SearchInput key="q" source="q" alwaysOn />, <TextInput key="title" source="title" />];

  return (
    <List filters={filters} actions={<PostActions filters={filters} />}>
      {/* ... */}
    </List>
  );
}
```

`ListToolbar` also injects `filters` into custom actions, so actions can receive the prop from the toolbar when they are rendered by `List`.

## Saved Queries

Saved queries are stored through React-Admin's store using the `${resource}.savedQueries` key. They are compatible with the standard saved query shape:

```ts
{
  label: string;
  value: {
    filter: object;
    displayedFilters: object;
    sort: {
      field: string;
      order: string;
    }
    perPage: number;
  }
}
```

## Props

| Prop           | Type                         | Default                            | Description                                                              |
| -------------- | ---------------------------- | ---------------------------------- | ------------------------------------------------------------------------ |
| `filters`      | `ReactElement[]`             | `[]`                               | List filter inputs. Only non-`alwaysOn` filters are shown in the picker. |
| `groups`       | `Record<string, string>`     | `{ standard: 'Standard filters' }` | Display labels for `filterGroup` values.                                 |
| `defaultGroup` | `string`                     | `standard`                         | Group used for filters without `filterGroup`.                            |
| `className`    | `string`                     |                                    | Applied to the trigger button.                                           |
| `size`         | MUI `ButtonProps['size']`    | `small`                            | Trigger button size.                                                     |
| `variant`      | MUI `ButtonProps['variant']` | `text`                             | Trigger button variant.                                                  |

## Notes

- The component returns `null` when there are no optional filters, no saved queries and no active filters.
- For custom filter renderers passed as a single React element instead of an array, Applica `List` keeps the previous behavior and does not render `FilterPicker` automatically.