# MultiSortPlugin

> _Since v0.1.1_

Multi-Sort Plugin for tbw-grid

Enables sorting by multiple columns at once—hold Shift and click additional column
headers to build up a sort stack. Priority badges show the sort order, so users
always know which column takes precedence.

## Installation

```ts
import { MultiSortPlugin } from '@toolbox-web/grid/plugins/multi-sort';
```

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Click header` | Sort by column (clears other sorts) |
| `Shift + Click` | Add column to multi-sort stack |
| `Ctrl + Click` | Toggle sort direction |

## Events

| Event | Detail | Description |
|-------|--------|-------------|
| `sort-change` | `{ sortModel: SortModel[] }` | Fired when sort changes |

## [Configuration Options](/grid/plugins/multi-sort/interfaces/multisortconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `maxSortColumns?` | <code>number</code> | Maximum number of columns that can be sorted simultaneously. Once the limit is reached, adding a new sort column replaces the oldest one. |
| `showSortIndex?` | <code>boolean</code> | Whether to show numbered badges (1, 2, 3…) on sorted column headers to indicate sort precedence. Disable for a cleaner look when precedence is not important to the user. |

## Examples

### Basic Multi-Column Sorting

```ts
import { queryGrid } from '@toolbox-web/grid';
import { MultiSortPlugin } from '@toolbox-web/grid/plugins/multi-sort';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name', sortable: true },
    { field: 'department', header: 'Department', sortable: true },
    { field: 'salary', header: 'Salary', type: 'number', sortable: true },
  ],
  plugins: [new MultiSortPlugin({ maxSortColumns: 3, showSortIndex: true })],
};

grid.on('sort-change', ({ sortModel }) => {
  console.log('Active sorts:', sortModel);
});
```

### Initial Sort Configuration

```ts
new MultiSortPlugin({
  initialSort: [
    { field: 'department', direction: 'asc' },
    { field: 'salary', direction: 'desc' },
  ],
})
```

## See Also

- [`MultiSortConfig`](/grid/plugins/multi-sort/interfaces/multisortconfig.md) for all configuration options
- [`SortModel`](/grid/plugins/multi-sort/interfaces/sortmodel.md) for the sort model structure

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

## Methods

### getSortModel()

Get the current sort model.

```ts
getSortModel(): SortModel[]
```

#### Returns

`SortModel[]` - Copy of the current sort model

***

### setSortModel()

Set the sort model programmatically.

```ts
setSortModel(model: SortModel[]): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `model` | <code><a href="/grid/plugins/multi-sort/interfaces/sortmodel/">SortModel</a>[]</code> | New sort model to apply |

***

### clearSort()

Clear all sorting.

```ts
clearSort(): void
```

***

### getSortIndex()

Get the sort index (1-based) for a specific field.

```ts
getSortIndex(field: string): number | undefined
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `field` | <code>string</code> | Field to check |

#### Returns

`number | undefined` - 1-based index or undefined if not sorted

***

### getSortDirection()

Get the sort direction for a specific field.

```ts
getSortDirection(field: string): "desc" | "asc" | undefined
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `field` | <code>string</code> | Field to check |

#### Returns

`"desc" | "asc" | undefined` - Sort direction or undefined if not sorted

***