npm package: @n3/react-filters
Description: Filters component for react applications
Latest version: 0.11.2

## ⚠️ ATTENTION ⚠️

Проект перемещён в [главный репозиторий компонентов](https://gitlab.develop.netrika.ru/web/n3components/tree/master/packages/react-filters).

# @n3/react-filters

## Установка

```
npm install @n3/react-filters
```

или

```
yarn add @n3/react-filters
```


## API

### Использование

```
import Filters from '@n3/react-filters';


...

<Filters
  isAdaptive={isAdaptive}
  filters={filters}
  filterData={filterData}
  values={values}
  errors={errors}
  appliedFilters={appliedFilters}
  canReset={canReset}
  setValues={setValues}
  applyFilters={applyFilters}
  handleReset={handleReset}
  typeKey={typeKey}
  labelKey={labelKey}
  filtersBlockComponent={filtersBlockComponent}
/>
```

### Props

 - `isAdaptive`: Boolean - необязательное, включить ли адаптивное поведение фильтров, по умолчанию `true`
 - `values`: Object - необязательное, текущие значения фильтров, по умолчанию `{}`
 - `errors`: Object - необязательное, текущие ошибки фильтров, по умолчанию `{}`
 - `appliedFilters`: Object - необязательное, значения применённых фильтров, по умолчанию `{}`
 - `canReset`: Boolean - необязательное, возможен ли сброс фильтров, по умолчанию `false`
 - `setFiltersValues`: Function - обязательное, хэндлер, срабатывающий при изменении значений фильтров. Принимает объект изменённых фильтров
 - `setAndApplyFilters`: Function - обязательное, аналогично, `setFiltersValues`, но должно сразу применить фильтры с новыми значениями
 - `applyFilters`: Function - обязательное, функция применения фильтров
 - `handleReset`: Function - необязательное, функция сброса фильтров
 - `filters`: Object - обязательное, объект описаний используемых фильтров. Ключ - тип фильтра, значение - описание фильтра
 - `filterData`: Array - обязательное, массив используемых фильтров
   - `name` - обязательное, название фильтра
   - `label` - обязательное, заголовок фильтра, ключ может быть изменён с помощью свойства `labelKey`
   - `type` - обязательное, тип фильтра, ключ может быть изменён с помощью свойства `typeKey`
   - `required` - необязательное, признак обязательности фильтра - отображается звёздочка вместе с заголовком, пустые фильтры с признаком `required` блокируют кнопку `Найти`, ключ может быть изменён с помощью свойства `requiredKey`  
 - `typeKey`: String - необязательное, ключ для получения типа фильтра, по умолчанию `type`
 - `labelKey`: String - необязательное, ключ для получения заголовка фильтра, по умолчанию `label`
 - `requiredKey`: String - необязательное, ключ для получения признака обязательности фильтра, по умолчанию `required`
 - `fastFiltersNumber` - Number, необязательное, количество быстрых фильтров, по умолчанию 0
 - `collapsibleButtonText`: Function | String - необязательное, текст или функция, возвращающая текст, для кнопки раскрытия/скрытия блока с фильтрами, по умолчанию `Все фильтры`, в качестве аргумента функции передаётся внутреннее состояние блока `{ opened: boolean }`  
 - `resetButtonText`: String - необязательное, текст для кнопки сброса всех фильтров, по умолчанию `Сбросить` 
 - `actionsBlock`: Element - необязательное, группа кнопок, расположенных в верхнем-правом углу блока с фильтрами
 - `filtersBlockComponent`: Function - необязательное, кастомный компонент блока фильтров. Принимает `props`:

   - `isAdaptive` - из компонента `Filters`
   - `filters` - из компонента `Filters`
   - `filterData` - из компонента `Filters`
   - `labelKey` - из компонента `Filters`
   - `typeKey` - из компонента `Filters`
   - `values` - из компонента `Filters`
   - `errors` - из компонента `Filters`
   - `setValues` - из компонента `Filters`
   - `applyFilters` - асинхронная функция, сначала вызывает `applyFilters` из компонента `Filters`, затем в случае успеха закрывает блок фильтров. Для обозначения ошибки применения фильтров нужно бросить исключение `ApplyFiltersError`.
 - `styles`: Object - необязательное, принимает объект, ключи которого представляют различные внутренние компоненты, составляющих блок с фильтрами
   -  `filtersBlock`: Function, возвращает новые стили для элемента, содержащего фильтры 
   -  `filterBlock`: Function, возвращает новые стили для фильтра
   -  `actionsBlock`: Function, возвращает новые стили для группы кнопок, расположенных в верхнем-правом углу блока с фильтрами
   -  `appliedIndicator`: Function, возвращает новые стили для индикатора применения фильтра

```
import { ApplyFiltersError } from '@n3/react-filters';

async function applyFilters() {

  ...

  throw new ApplyFiltersError();

}
```

### Описания фильтров

Каждое описание фильтра иммет формат [@n3/filters-utils](https://www.npmjs.com/package/@n3/filters-utils), и представляется объектом вида:

  - `component` - react-компонент фильтра. Принимает следующие props:

    - `isFastFilter`: Boolean - отрендерен ли фильтр в блоке быстрых фильтров
    - `label`: String - лейбл поля
    - `payload`: Object - объект, переданный в `filtersData`
    - `values`: Object - текущие значения фильтров
    - `errors`: Object - текущие ошибки фильтров
    - `filters`: Object - объект, переданный в `Filters`
    - `setFiltersValues`: Function - из родительского компонента
    - `setAndApplyFilters`: Function - из родительского компонента
    - `setValues`: Function - хэндлер, который нужно вызывать при изменении значения фильтра. Первым аргументом принимает объект, ключами которого являются имена изменённых фильтров, а значениями - значения фильтров. Для быстрых фильтров принимает `setAndApplyFilters`, а для обычных - `setFiltersValues`

  - `checkForApplied`: Function - необязательная, функция проверки, применён ли фильтр. Первым аргументом принимает `payload` (объект, переданный в `filtersData`), а вторым - `appliedFilters` главного компонента. Должна возвращать массив булево значение. По умолчанию, берёт значение из `appliedFilters` по ключу `payload.name` и проверяет его на истинность

  - `getNames`: Function - необязательная, смотри [@n3/filters-utils](https://www.npmjs.com/package/@n3/filters-utils)

  - `serializeValues`: Function - необязательная, смотри [@n3/filters-utils](https://www.npmjs.com/package/@n3/filters-utils)

  - `checkCanReset`: Function - необязательная, смотри [@n3/filters-utils](https://www.npmjs.com/package/@n3/filters-utils)

  - `parseValues`: Function - необязательная, смотри [@n3/filters-utils](https://www.npmjs.com/package/@n3/filters-utils)

## Интеграция c react-filterlist

Рекомендуемый способ использования. Инкапсулирует сериализацию, парсинг, изменения, отслеживание возможности сброса фильтров, передачу параметров `values`, `errors` и `appliedFilters`.

Filterlist нужно установить отдельно.

```
yarn add @vtaits/filterlist @vtaits/react-filterlist
```

### Импорт

```
// commonjs
import { Filterlist, Filters } from '@n3/react-filters/lib/filterlist';

// es modules
import { Filterlist, Filters } from '@n3/react-filters/es/filterlist';
```

### Использование

```
<Filterlist
  filters={filters}
  filterData={filterData}
  labelKey={labelKey}
  typeKey={typeKey}
  loadItems={loadItems}
  parseFiltersAndSort={parseFiltersAndSort}
  onChangeLoadParams={onChangeLoadParams}
  {...otherFilterlistProps}
>
  {({
    isListInited,
    listState,
    listActions,
  }) => (
    <div>
      <Filters
        isAdaptive={isAdaptive}
        filtersBlockComponent={filtersBlockComponent}
      />

      {otherJsx}
    </div>
  )}
</Filterlist>
```

- **filters** - смотри выше;
- **filterData** - смотри выше;
- **labelKey** - смотри выше;
- **typeKey** - смотри выше;
- **isAdaptive** - смотри выше;
- **filtersBlockComponent** - смотри выше;

- **loadItems** - аналогично функции **loadItems** из [filterlist](https://www.npmjs.com/package/@vtaits/filterlist), но принимает вторым аргументом объект `{ serializedValues: {...} }`, где `serializedValues` - сериализованные значения фильтров;
- **onChangeLoadParams** - аналогично функции **onChangeLoadParams** из [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist), но принимает вторым аргументом объект `{ serializedValues: {...} }`, где `serializedValues` - сериализованные значения фильтров;
- **parseFiltersAndSort** - аналогично функции **parseFiltersAndSort** из [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist), но принимает вторым аргументом объект `{ parseValues }`, где `parseValues` - **асинхронная** функция парсинга значений, принимающая только один аргумент - объект значений;

- **otherFilterlistProps** - остальные параметры [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist) за исключением `isRecountAsync`, оно всегда `true`;

- **isListInited** - смотри [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist);
- **listState** - смотри [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist);
- **listActions** - смотри [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist);

## Стили

### Готовые стили

```
import '@n3/react-filters/dist/n3-react-filters.css';
```

### Исходные postcss-стили

```
import '@n3/react-filters/postcss/n3-react-filters.css';
```

Для сборки необходим плагин [precss](https://github.com/jonathantneal/precss), а также настроен импорт из директории node_modules.

### Исходные postcss-стили без определения css-переменных

```
import '@n3/react-filters/postcss/without-variables.css';
```

Для сборки необходим плагин [precss](https://github.com/jonathantneal/precss), а также настроен импорт из директории node_modules.