# GroupingColumnsPlugin

> _Since v0.1.1_

Column Grouping Plugin for tbw-grid

Enables visual grouping of columns under shared headers. Supports two approaches:
declarative `columnGroups` at the grid level, or inline `group` property on columns.

## Installation

```ts
import { GroupingColumnsPlugin } from '@toolbox-web/grid/plugins/grouping-columns';
```

## Grid Config: `columnGroups`

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Unique group identifier |
| `header` | `string` | Display label for the group header |
| `children` | `string[]` | Array of column field names in this group |

## Column Config: `group`

| Type | Description |
|------|-------------|
| `string` | Simple group ID (used as both id and label) |
| `{ id: string; label?: string }` | Group object with explicit id and optional label |

## [Configuration Options](/grid/plugins/grouping-columns/interfaces/groupingcolumnsconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `columnGroups?` | <code><a href="/grid/plugins/grouping-columns/interfaces/columngroupdefinition/">ColumnGroupDefinition</a>[]</code> | Declarative column group definitions. When provided here, takes precedence over `gridConfig.columnGroups`. |
| `groupHeaderRenderer?` | <code>(params: <a href="/grid/plugins/grouping-columns/interfaces/groupheaderrenderparams/">GroupHeaderRenderParams</a>) =&gt; string &#124; void &#124; HTMLElement</code> | Group header renderer called for each column group. Receives the group's `id`, `label`, and `columns` in the params, so a single function can handle all groups or differentiate per group via `params.id`. |
| `showGroupBorders?` | <code>boolean</code> | Whether to show group borders (default: true) |
| `lockGroupOrder?` | <code>boolean</code> | Prevent columns from being reordered outside their group. When enabled, column moves that would break group contiguity are blocked. Works with both header drag-and-drop and visibility panel drag-and-drop. |

## Examples

### Declarative columnGroups (Recommended)

```ts
import '@toolbox-web/grid';
import { GroupingColumnsPlugin } from '@toolbox-web/grid/plugins/grouping-columns';

grid.gridConfig = {
  columnGroups: [
    { id: 'personal', header: 'Personal Info', children: ['firstName', 'lastName', 'email'] },
    { id: 'work', header: 'Work Info', children: ['department', 'title', 'salary'] },
  ],
  columns: [
    { field: 'firstName', header: 'First Name' },
    { field: 'lastName', header: 'Last Name' },
    // ...
  ],
  plugins: [new GroupingColumnsPlugin()],
};
```

### Inline group Property

```ts
grid.gridConfig = {
  columns: [
    { field: 'firstName', header: 'First Name', group: { id: 'personal', label: 'Personal Info' } },
    { field: 'lastName', header: 'Last Name', group: 'personal' }, // string shorthand
  ],
  plugins: [new GroupingColumnsPlugin()],
};
```

## See Also

- [`GroupingColumnsConfig`](/grid/plugins/grouping-columns/interfaces/groupingcolumnsconfig.md) for all configuration options
- [`ColumnGroup`](/grid/plugins/grouping-columns/interfaces/columngroup.md) for the group structure
- ReorderPlugin for drag-to-reorder within groups

> **Extends** [BaseGridPlugin](/docs/grid-api-plugin-development-classes-basegridplugin--docs)
>
> Inherited methods like `attach()`, `detach()`, `afterRender()`, etc. are documented in the base class.

## Methods

### detect()

Auto-detect column groups from column configuration.
Detects both inline `column.group` properties and declarative `columnGroups` config.

```ts
static detect(rows: readonly any[], config: any): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `rows` | <code>readonly any[]</code> |  |
| `config` | <code>any</code> |  |

***

### isGroupingActive()

Check if column groups are active.

```ts
isGroupingActive(): boolean
```

#### Returns

`boolean` - Whether grouping is active

***

### getGroups()

Get the computed column groups.

```ts
getGroups(): ColumnGroup<any>[]
```

#### Returns

`ColumnGroup<any>[]` - Array of column groups

***

### getGroupColumns()

Get columns in a specific group (aggregated across all fragments).

```ts
getGroupColumns(groupId: string): ColumnConfig<any>[]
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `groupId` | <code>string</code> | The group ID to find |

#### Returns

`ColumnConfig<any>[]` - Array of columns in the group

***

### refresh()

Refresh column groups (recompute from current columns).

```ts
refresh(): void
```

***