import { Meta, Canvas, ArgTypes } from '@storybook/addon-docs/blocks'
import * as ColumnGroupStories from './column-groups.stories.tsx'

<Meta title="pv-grid/Components/Grid/Column grouping" />

# Column grouping

Column groups are used to visually group columns together in the grid header using the [Grid column group header](https://design.planview.com/components/grid/grid-column-group-header).

## Configuration

Grouping is configured using the `columnGroups` prop which is an array of `ColumnGroup` objects. A column group is defined by at least three properties:

- `id` - a unique identifier for the group.
- `label` - the text to display in the group header.
- `children` - an array of column- or group-id's that are children of this group. _Note: A child column or group can only be associated with one group._
- `border` - optional, can be set to `both`, `left`, or `right` to show full grid height borders for a column group.

### Type definition

<ArgTypes of={ColumnGroupStories} />

### Simple usage

<Canvas of={ColumnGroupStories.ColumnGrouping} />

### Multiple levels of grouping

The grid supports a **maximum two levels** of column-grouping resulting in a total of three header rows (including the columns themselves).

<Canvas of={ColumnGroupStories.ColumnGroupingMultiple} />

### Showing full grid height borders

In some cases, it can be useful to show the full grid height borders for each column group. This can be achieved by setting the `border` property to `both` (or `left`/`right`) on the `ColumnGroup` object.

<Canvas of={ColumnGroupStories.ColumnGroupingWithBorder} />

### Groups sticky and locked location

Just like columns, column groups can be sticky and locked. However; the column group's `sticky` and `locked` properties **will override any child group or column setting if they happen to differ**.

### Resizing Groups

If you grab the group resize bar, it resizes each child in the group evenly distributing the reduced or added width with regards to cell max- and min-widths. If you grab the child resize bar, only that one column will be resized.

### Rearranging Groups

By dragging a column group header, the user can change the position of the entire column group simultaneously, rearranging all its contained columns among other column groups or individual columns within the grid.

When dragging a column header or a group header that is contained within a parent group, its position will be moved only within the boundaries of its group. This means that users can rearrange the order of items within a parent group, but they cannot drag a column or column group outside of the boundaries defined by the group.