npm package: @n3/react-configurable-table
Description: Table with configurable columns for react applications
Latest version: 2.1.1

# @n3/react-configurable-table

Таблица с настройкой видимости колонок.

## Установка

```sh
npm install @n3/react-configurable-table styled-components --save
```

или

```sh
yarn add @n3/react-configurable-table styled-components
```

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

Для стандартного использования библиотека предоставляет три компонента: `TableProvider`, `TableConsumer` и `SettingsConsumer`.

```typescript
import {
  TableProvider,
  TableConsumer,
  SettingsConsumer,
} from '@n3/react-configurable-table';
```

### TableProvider

Создаёт контекст для таблицы и виджета настройки колонок.

#### props

- `columns` - обязательное, объект, ключами которого являются id колонок, а значениями - их параметры. Вид объект параметров:

  - `title` - необязательное, строка, выводится в шапке таблицы и пунктах меню настроек;

  - `type` - необязательное, строка, используется для задания кастомной функции рендера ячеек данной колонки через `bodyCellRenderers`;

  - `childs` - необязательное, массив строк, список id дочерних колонок. Если их нет, то колонка является _листовой_;

  - `canDisable` - необязательное, булево, может ли быть изменена видимость колонки, по-умолчанию `true`;

  - `isFooterLeaf` - необязательное, булево, является ли колонка листовой для футера;

  - `payload` - необязательное, объект, `props` каждой шапки и ячейки таблицы этого столбца;

  - `thPayload` - необязательное, объект, `props` каждой шапки таблицы этого столбца, перекрывает `payload`;

  - `footerPayload` - необязательное, объект, `props` каждой ячейки футера таблицы этого столбца, перекрывает `payload`;

  - `tdPayload` - необязательное, объект, `props` каждой ячейки таблицы этого столбца, перекрывает `payload`;

  - `renderCell` - необязательное, функция, используется для рендера контента ячейки, если не задан её `type` в `bodyCellRenderers`, принимает аргументы:

    - `row` - строка данных;

    - `columnId` - id колонки;

    - `column` - элемент объекта `columns`;

  - `renderHeadCell` - необязательное, функция, используется для рендера шапки таблицы, принимает аргументы:

    - `columnId` - id колонки;

    - `column` - элемент объекта `columns`;

  - `renderFooterCell` - необязательное, функция, используется для рендера футера таблицы, принимает аргументы:

    - `row` - строка данных `footerData`;

    - `columnId` - id колонки;

    - `column` - элемент объекта `columns`;

  - `renderSettingsOption` - необязательное, функция, используется для рендера пункта в меню настроек, принимает аргументы:

    - `columnId` - id колонки;

    - `column` - элемент объекта `columns`;

- `rootIds` - обязательное, список корневых колонок;

- `disabledColumns` - необязательное, выключенные колонки по умолчанию. Объект, ключами которого являются id листовых колонок, а значениями - выключена ли данная колонка. Если колонка не объявлена в данном объекте, значит, она не выключена;

- `onDisabledColumnsChange` - необязательное, функция, вызывается при изменении выключенных колонок. Первым аргументом принимает `disabledColumns`;

- `data` - обязательное, масив объектов, используется для вывода данных в теле таблицы. По умлочанию каждая листовая колонка берёт значение по ключу, являющемуся своим id, и выводит в td, может быть переопределено при помощи `renderBodyCell` или `bodyCellRenderers` (смотри ниже);

- `headData` - необязательное, масив объектов, используется для вывода данных в шапке таблицы при помощи `renderHeadCell` (смотри ниже);

- `footerData` - необязательное, масив объектов, используется для вывода данных в футере таблицы.

### SettingsConsumer

Дропдаун с настройками видимости колонок.

#### props

- `setColumnsState` - обязательное, функция, обработчик изменения выключенных колонок;

- `minColumnsNumber` - необязательное, минимальное количество листовых колонок, которое должно показываться на экране, по-умолчанию `2`;

- `searchPlaceholder` - необязательное, строка, плейсхолдер поля поиска в дропдауне, по-умолчанию `"Поиск"`;

- `buttonText` - необязательное, строка, текст кнопки-дропдауна настроек, по-умолчанию `"Настройка колонок"`;

- `hasSearch` - необязательное, булево, доступен ли поиск по колонкам, по-умолчанию `true`;

- `canCheckAll` - необязательное, булево, доступна ли опция выключения/включения всех колонок, по-умолчанию `true`;

- `checkAllText` - необязательное, строка, текст чекбокса выключения/включения всех колонок, по-умолчанию `"Все"`;

- `placement` - необязательное, строка, положение popper-элемента, по-умолчанию "bottom-end". [Список возможных вариантов](https://github.com/FezVrasta/popper.js/blob/master/docs/_includes/popper-documentation.md#Popper.placements);

- `popperStyle` - необязательное, объект, дополнительные стили popper-компонента;

- `offsetDistance`- необязательное, число, расстояние от дропдауна до кнопки;

- `className` - внутенний класс, который должен быть присвоен корневому dom-елементу;

- `settingsToggleButtonId` - необязательное, строка, id кнопки настройки колонок.

### TableConsumer

Компонент, строящий таблицу по настройкам колонок и их видимости.

#### props

- `renderHeadCell` - необязательное, функция рендера элементов `headData` в th. Принимает аргументы `row` (элемент `headData`), `columnId` (id колонки) и `column` (элемент объекта `columns`). По умолчанию возвращает `row[columnId]`;

- `renderLeafHeadCell` - необязательное, функция рендера листовых элементов `columns` в шапке. По умолчанию возвращает `column.title`. Принимает аргументы:

  - `renderedTitle` - тайтл колонки, полученный в результате вызова `renderHeadCell`, или `column.title`, если не определено `renderHeadCell`;

  - `columnId` (id колонки);

  - `column` (элемент объекта `columns`);

- `shouldRenderHeadRow` - необязательное, функция, определяющая, нужно ли отображать строку данных шапки. Принимает аргументы:

  - `row` - строка данных;

  - `index` - индекс строки в массиве;

  - `visibleColumnsIds` - массив id видимых колонок;

  - `notDisabledColumnsIds` - массив id не выключенных колонок;

- `renderBodyCell` - необязательное, функция рендера элементов `data` в теле таблицы. По умолчанию возвращает `row[columnId]`. Принимает аргументы:
  - `row` - строка данных;
  - `columnId` - id колонки;
  - `column` - элемент объекта `columns`;

- `bodyCellRenderers` - необязательное, объект, ключами которого являются `type` элементов объекта `columns`, а значениями - функции рендера ячеек колонки данного типа, аналогичные `renderBodyCell`. Если для данного `type` функция не определена, рендер производится через `renderBodyCell`;

- `getBodyCellProps` - необязательное, функция, собирающая дополнительные props компонента `tdComponent`. По умолачанию возвращает `{}`. Принимает аргументы:
  - `row` - строка данных;
  - `columnId` - id колонки;
  - `column` - элемент объекта `columns`;

- `shouldRenderBodyRow` - необязательное, функция, определяющая, нужно ли отображать строку данных. Принимает аргументы:

  - `row` - строка данных;

  - `index` - индекс строки в массиве;

  - `visibleColumnsIds` - массив id видимых колонок;

  - `notDisabledColumnsIds` - массив id не выключенных колонок;

- `tableProps` - необязательное, объект, дополнительные `props` table-компонента;

- `tableComponent` - необязательное, react-компонент, переопределённый table-компонент;
- `trComponent` - необязательное, react-компонент, переопределённый tr-компонент;
- `theadComponent` - необязательное, react-компонент, переопределённый thead-компонент;
- `thComponent` - необязательное, react-компонент, переопределённый th-компонент;
- `tbodyComponent` - необязательное, react-компонент, переопределённый tbody-компонент;
- `tdComponent` - необязательное, react-компонент, переопределённый td-компонент;
- `tfootComponent` - необязательное, react-компонент, переопределённый tfoot-компонент;

- `renderRow` - необязательное, функция рендера строк таблицы по строке данных. Рендерит элемент массива, поэтому свойство `key` обязательно для корневого узла. По умолчанию рендерит один `trComponent` с вложенными `tdComponent`. Примнимает первым аргументом объект следующих свойств:

  - `trComponent` - смотри выше;
  - `row` - строка данных;
  - `index` - номер элемента массива;
  - `renderRow` - для рекурсивного рендера;
  - `renderCells` - функция рендера ячеек по строке с учётом `disabledColumns` и кастомного рендера;

  Пример:

  ```tsx
  const renderRow = ({
    trComponent: Tr,
    row,
    index,
    renderCells,
  }) => (
    <Tr key={index}>
      {renderCells(row)}
    </Tr>
  );
  ```

- `maxColumnsLength` - необязательное, число, максимальное количество колонок для рендера;

- `isHeadTreeHidden` - необязательное, булево, скрыть ли заголовки колонок в шапке, по-умолчанию `false`.

### PropTypes

```
import {
  columnShape,
  columnsObjectOf,
  disabledColumnsObjectOf,
  basePropTypes,
  settingsDropdownPropTypes,
  bodyCellRenderersObjectOf,
  tablePropTypes,
} from '@n3/react-configurable-table';
```

- `columnShape` - объект параметров колонки;
- `columnsObjectOf` - объект `columns` (смотри выше);
- `disabledColumnsObjectOf` - объект `disabledColumns` (смотри выше);
- `basePropTypes` - базовые `propPypes` компоенентов `Table` и `SettingsDropdown` (содержит `columns`, `disabledColumns` и `rootIds`);
- `settingsDropdownPropTypes` - `propPypes` компоенента `SettingsDropdown`;
- `bodyCellRenderersObjectOf` - объект `bodyCellRenderers` (смотри выше);
- `tablePropTypes` - `propPypes` компонента `Table`.

### Flow

```
import type {
  ColumnType,
  ColumnsObjectType,
  DisabledColumnsType,
  BasePropsType,
  SettingsDropdownPropsType,
  TablePropsType,
} from '@n3/react-configurable-table';
```

- `ColumnType` - параметры колонки;
- `ColumnsObjectType` - объект `columns` (смотри выше);
- `DisabledColumnsType` - объект `disabledColumns` (смотри выше);
- `BasePropsType` - базовые `props` компоенентов `Table` и `SettingsDropdown` (содержит `columns`, `disabledColumns` и `rootIds`);
- `SettingsDropdownPropsType` - `props` компоенента `SettingsDropdown`;
- `BodyCellRenderersType` - объект `bodyCellRenderers` (смотри выше);
- `TablePropsType` - `props` компонента `Table`.

### Стилизация меню

Делается с помощью заменяемых компонентов.

```javascript
import {
  SettingsConsumer,
} from '@n3/react-configurable-table';

...

<SettingsConsumer
  {...props}
  components={{
    Checkbox,
    DropdownButton,
    Popper,
    SearchInput,
    Settings,
    SettingsItem,
  }}
/>
```

## Расширенное использование

Рекомендуется только для написания сторонних библиотек.

### Table

```
import { Table } from '@n3/react-configurable-table';
```

Аналогично `TableConsumer`, но требуется вручную передать параметры `columns`, `rootIds`, `disabledColumns`, `data` и `headData`.

- `columns` - аналогично `TableProvider`;

- `rootIds` - аналогично `TableProvider`;

- `data` - аналогично `TableProvider`;

- `headData` - аналогично `TableProvider`;

- `disabledColumns` - текущее состояние выключенных колонок.

### SettingsDropdown

```
import { SettingsDropdown } from '@n3/react-configurable-table';
```

Аналогично `SettingsConsumer`, но требуется вручную передать параметры `columns`, `rootIds`, `disabledColumns` и `setColumnsState`.

- `columns` - аналогично `TableProvider`;

- `rootIds` - аналогично `TableProvider`;

- `disabledColumns` - текущее состояние выключенных колонок;

- `setColumnsState` - обязательное, функция, вызывается при изменении видимости колонок, первым аргументом принимает новое значение `disabledColumns`.

### useColumns

Хук, возвращающий параметры:

- `columns`
- `data`
- `disabledColumns`
- `footerData`
- `headData`
- `rootIds`
- `setColumnsState`

Использует контекст, созданный `TableProvider`.

```
import { TableProvider, withColumns } from '@n3/react-configurable-table';

...

const SomethingWithColumns = withColumns(Something);

...

<TableProvider
  columns={columns}
  rootIds={rootIds}
>
  <SomethingWithColumns />
</TableProvider>
```

### getLeafColumnsIds

Утилита для получения плоского списка листовых колонок.

```javascript
import { getLeafColumnsIds } from ' @n3/react-configurable-table';

const leafColumnsIds = getLeafColumnsIds(columns, rootIds);
```

## Локальная разработка

Репозиторий использует стабильную версию [yarn](https://yarnpkg.com/getting-started).

[Инструкция по установке](https://yarnpkg.com/getting-started/install).

### Команды

- `yarn build` - сборка;

- `yarn clean` - удалить все собранне файлы;

- `yarn test` - валидация кода;

- `yarn start` - запуск [storybook](https://storybook.js.org/) с примерами.