npm package: @inventi/mailstep-common-grid
Description: [![ReactJs][react-image]][react-url] [![TypeScript][typescript-image]][typescript-url] [![Redux][redux-image]][redux-url] [![Storybook][storybook-image]][storybook-url] [![Download Count][download-image]][download-url] [![GitHub license][license-image]][l
Author: Inventi Development Ltd.
Latest version: 1.2.4

# Inventi Common Grid
[![ReactJs][react-image]][react-url]
[![TypeScript][typescript-image]][typescript-url]
[![Redux][redux-image]][redux-url]
[![Storybook][storybook-image]][storybook-url]
[![Download Count][download-image]][download-url]
[![GitHub license][license-image]][license-url]

[react-image]: https://img.shields.io/badge/ReactJS-%5E17.x-blue.svg
[react-url]: https://reactjs.org
[typescript-image]: https://img.shields.io/badge/typescript-4.3.5-blue
[typescript-url]: https://www.typescriptlang.org/
[storybook-image]: https://img.shields.io/badge/storybook-6.4.12-blue
[storybook-url]: https://storybook.js.org/
[redux-image]: https://img.shields.io/badge/redux-4.0.5-blue
[redux-url]: https://redux.js.org/
[download-image]: http://img.shields.io/npm/dm/@inventi/mailstep-common-grid.svg?style=flat
[download-url]: http://www.npmjs.com/package/@inventi/mailstep-common-grid
[license-image]: https://img.shields.io/badge/license-MIT-blue.svg
[license-url]: https://opensource.org/licenses/MIT

Robust, complex and sophisticated component for datagrid rendering.

- server side and client side sorting
- server side and client side filtering
- moving columns via drag and drop
- column grouping
- easy to be styled
- redux support for external control
- high level of customization

## Installation
```
yarn add @inventi/mailstep-common-grid
```

## Usage
```js
const columnDefinitions = [
     { name: 'username', title: 'User name', flexBasis: 160 },
     { name: 'age', title: 'Age', flexBasis: 160, filteringType: 'number', },
     { name: 'isAdmin', title: 'Admin', flexBasis: 160, filteringType: 'flag', },
]

const data = [
    { id: 1, username: 'John deen', age: 27, isAdmin: true },
    { id: 2, username: 'Emily Watson', age: 22, isAdmin: false },
]

const gridActions = {
  setPage: (number) => console.log('setPage', number),
  setRowsPerPage: (number) => console.log('setRowsPerPage', number),
  addFilter: (column, value, filterProps) => console.log('add filter for column', column ),
}

const gridSelectors = {
    page: 1,
    rowsPerPage: 10
}

const MyPage = () =>
    <CommonGrid
        columnsDefinitions={columnDefinitions}
        rowsData={data}
        gridActions={gridDummyActions}
        gridSelectors={gridSelectors}
    />
```


## Props

### `actionColumnDefinition`: ActionColumn
Used to define the first column of the grid. This column usually contains buttons for displaying detail or editing data in a row and other features.

#### ActionColumn:
Object with keys:
|        Name         |    Type                         |  Required  | Description                           | Default   |
| ------------------- | ------------------------------- | :--------: | :------------------------------------ | :-------- |
| **actionOptions**   |  `Array<BatchAction>`           | `no`       | handlers for batch action on grid     | []        |  
| **canRowEdit**      |  `boolean`                      | `no`       | shows / hides the edit button         | false     |  
| **canRowRead**      |  `boolean`                      | `no`       | shows / hides the read button         | false     |  
| **createLink**      |  `(params) => string`           | `no`       | callback for above buttons            | -         |  
| **forceCheckboxes** |  `boolean`                      | `no`       | displays checkboxes in each row       | false     |  

#### BatchAction
Object with keys:
|        Name         |    Type                         |  Required  | Description                           | Default   |
| ------------------- | ------------------------------- | :--------: | :------------------------------------ | :-------- |
| **value**           |  `string`                       | `yes`      |                                       | -         |  
| **label**           |  `string`                       | `yes`      |                                       | -         |  
| **isEnabled**       |  `(checkedRows) => boolean`     | `no`       |                                       | -         |

### `allowRowSelect`: boolean, default: false
Enable select a row by clicking.

### `className`: string, default: ''
Main className over the entire grid.

### `columnLayout`: 'normal' | 'no-scroll', default: normal
TODO

### `components`: Components
Used to define custom components in the grid. Object with keys:
|        Name         |    Type                         |  Required  | Description                           | Default   |
| ------------------- | ------------------------------- | :--------: | :------------------------------------ | :-------- |
| **Translator**      |  `React.ComponentType`          | `no`       | see TranslatorPublicInterfaceProps    | -         |  
| **Checkbox**        |  `React.ComponentType`          | `no`       | see CheckboxPublicInterfaceProps      | -         |  
| **Button**          |  `React.ComponentType`          | `no`       | see ButtonPublicInterfaceProps        | -         |
| **Switch**          |  `React.ComponentType`          | `no`       | see SwitchPublicInterfaceProps        | -         |
| **Paginator**       |  `React.ComponentType`          | `no`       | see PaginatorProps                    | -         |
| **ColumnTitle**     |  `React.ComponentType`          | `no`       | see ColumnTitleProps                  | -         |

#### TranslatorPublicInterfaceProps
Its a component with props
|        Name         |    Type                         |  Required  | Description                           | Default   |
| ------------------- | ------------------------------- | :--------: | :------------------------------------ | :-------- |
| **id**              |  `string`                       | `no`       |                                       | -         |  
| **defaults**        |  `string`                       | `no`       |                                       | -         |


#### CheckboxPublicInterfaceProps
Its a component with props
|        Name         |    Type                         |  Required  | Description                           | Default   |
| ------------------- | ------------------------------- | :--------: | :------------------------------------ | :-------- |
| **name**            |  `string`                       | `no`       |                                       | -         |  
| **label**           |  `string, JSX.Element`          | `no`       |                                       | -         |
| **onChange**        |  `(event) => void`              | `no`       |                                       | -         |
| **checked**         |  `boolean`                      | `no`       |                                       | -         |

#### ButtonPublicInterfaceProps
Its a component with props
|        Name         |    Type                         |  Required  | Description                           | Default   |
| ------------------- | ------------------------------- | :--------: | :------------------------------------ | :-------- |
| **children**        |  `React.ReactNode`              | `no`       |                                       | -         |  
| **type**            |  `button, submit, reset`        | `no`       |                                       | -         |
| **appearance**      |  `string`                       | `no`       |                                       | -         |
| **isLoading**       |  `boolean`                      | `no`       |                                       | -         |
| **disabled**        |  `boolean`                      | `no`       |                                       | -         |
| **margin**          |  `string`                       | `no`       |                                       | -         |
| **className**       |  `string`                       | `no`       |                                       | -         |
| **onClick**         |  `(event) => void`              | `no`       |                                       | -         |

#### SwitchPublicInterfaceProps
Its a component with props
|        Name         |    Type                         |  Required  | Description                           | Default   |
| ------------------- | ------------------------------- | :--------: | :------------------------------------ | :-------- |
| **name**            |  `string`                       | `no`       |                                       | -         |  
| **label**           |  `string`                       | `no`       |                                       | -         |
| **onChange**        |  `(event) => void`              | `no`       |                                       | -         |
| **checked**         |  `boolean`                      | `no`       |                                       | -         |

#### PaginatorProps
Its a component with props
|        Name         |    Type                         |  Required  | Description                           | Default   |
| ------------------- | ------------------------------- | :--------: | :------------------------------------ | :-------- |
| **page**            |  `number`                       | `yes`      |                                       | -         |  
| **itemCount**       |  `number`                       | `yes`      |                                       | -         |
| **itemPerPage**     |  `number`                       | `yes`      |                                       | -         |
| **onPageChange**    |  `(number) => void`             | `no`       |                                       | -         |

#### ColumnTitleProps
Custom component to replace column title and sorting indicator
|        Name         |    Type                         |  Required  | Description                           | Default   |
| ------------------- | ------------------------------- | :--------: | :------------------------------------ | :-------- |
| **title**            |  `string \| JSX.Element`       | `no`       |  title of the column                                     | -         |  
| **isSortable**       |  `boolean`                     | `yes`      |  can column be sorted                                     | -         |
| **sortValue**        |  `asc \| desc \| null`         | `yes`      |  current applied sort on this column                                      | -         |
| **onSetSort**         |  `(sortValue) => void`        | `no`       |  set new sort value for column                                     | -         |


### `columnsDefinitions`: Array<ColumnDefinition>
Defines the properties of each grid column.

#### ColumnDefinition type
Object with keys:
|        Name           |    Type                            |  Required  | Description                           | Default   |
| ----------------------| ---------------------------------- | :--------: | :------------------------------------ | :-------- |
| **name**              |  `string`                          | `yes`      |                                       | -         |  
| **group**             |  `string`                          | `no`       | Divides columns into the same groups. | -         |
| **systemName**        |  `string`                          | `no`       |                                       | -         |
| **systemFilter**      |  `string`                          | `no`       |                                       | -         |
| **title**             |  `string`                          | `no`       |                                       | -         |
| **filtering**         |  `boolean`                         | `no`       |                                       | -         |
| **filteringType**     |  `number, text, date, flag`        | `no`       |                                       | -         |
| **filterExtraProps**  |  `FilterExtraProps`                | `no`       |                                       | -         |
| **getFilterCriteria** |  `(value: string) => {[column]: any}`| `no`     |                                       | -         |
| **filterOptions**     |  `Array<Option>`                   | `no`       |                                       | -         |
| **sorting**           |  `boolean`                         | `no`       |                                       | -         |
| **formatRowValue**    |  `(row) => React.node`             | `no`       |                                       | -         |
| **cellComponent**     |  `React.ComponentType`             | `no`       | see DataCellProps                     | -         |
| **flexGrow**          |  `number`                          | `no`       |                                       | -         |
| **flexShrink**        |  `number`                          | `no`       |                                       | -         |
| **fixedSize**         |  `boolean`                         | `no`       |                                       | -         |
| **alwaysOn**          |  `boolean`                         | `no`       |                                       | -         |
| **defaultHidden**     |  `boolean`                         | `no`       |                                       | -         |

#### FilterExtraProps
Object with keys:
|        Name         |    Type        |  Required  | Description                           | Default   |
| ------------------- | -------------- | :--------: | :------------------------------------ | :-------- |
| **isMulti**         |  `boolean`     | `no`       |                                       | -         |  
| **comparators**     |  `any`         | `no`       |                                       | -         |  
| **filterTime**      |  `boolean`     | `no`       |                                       | -         |
| **decimals**        |  `number`      | `no`       |                                       | -         |
| **isFloat**         |  `boolean`     | `no`       |                                       | -         |

#### DataCellProps
|        Name         |    Type                                       |  Required  | Description                           | Default   |
| ------------------- | --------------------------------------------- | :--------: | :------------------------------------ | :-------- |
| **rowData**         |  `T`                                          | `no`       |                                       | -         |  
| **onRowAction**     |  `(id, field, value) => void | Promise<any>`  | `no`       |                                       | -         |  
| **column**          |  `ColumnDefinition`                           | `no`       |                                       | -         |

### `errorMessage`: string
If an error occurs somewhere on the page, typically while loading data into the grid, we can display it in the grid where the rows are rendered.

### `extraControlButtons`: Array<ExtraControlButton>
Buttons for other user actions can be displayed around the grid.

#### ExtraControlButton
Object with keys:
|        Name     |    Type                                           |  Required  | Description                           | Default   |
| --------------- | ------------------------------------------------- | :--------: | :------------------------------------ | :-------- |
| **node**        |  `React.ReactNode`                                | `no`       |                                       | -         |  
| **onClick**     |  `() => void`                                     | `no`       |                                       | -         |  
| **onSelect**    |  `(value: string) => void`                        | `no`       |                                       | -         |
| **label**       |  `React.node`                                     | `no`       |                                       | -         |
| **style**       |  `primary, secondary`                             | `no`       |                                       | -         |
| **options**     |  `Array<Option>`                                  | `no`       |                                       | -         |
| **position**    |  `top-left, top-right, bottom-left, bottom-right` | `no`       |                                       | -         |
| **hide**        |  `boolean`                                        | `no`       |                                       | -         |
| **hideChevron** |  `boolean`                                        | `no`       |                                       | -         |
| **disabled**    |  `boolean`                                        | `no`       |                                       | -         |

### `filters`: FiltersConfig
### `gridActions`: GridActionsType
### `gridSelectors`: GridSelectorsType
### `hideAllControls`: boolean, default: false
If set, only grid and paginator will be rendered. No other control above and below grid will be rended. Use if you want to handle grid configuration in custom way
### `hideColumnConfig`: boolean, default: false
### `isLoading`: boolean, default: isLoading
### `minColumnWidth`: number, default: 30
### `onBatchAction`: (action: batchAction, affectedRows: T[]) => void
### `onRowAction`: (id: string, field: string, value: any) => void
### `onRowEditClick`: (id: string, props: TData) => void
### `onRowReadClick`: (id: string, props: TData) => void
### `onRowClick`: (id: string, props: TData) => void
### `rowsData`: RowProps[]
### `totalRowsCount`: number, default: 0






## Contributors

## License

[MIT](LICENSE.md)