# PinnedRowsPlugin

> _Since v0.1.1_

Pinned Rows (Status Bar) Plugin for tbw-grid

Creates fixed status bars at the top or bottom of the grid for displaying aggregations,
row counts, or custom content. Think of it as the "totals row" you'd see in a spreadsheet—
always visible regardless of scroll position.

## Installation

```ts
import { PinnedRowsPlugin } from '@toolbox-web/grid/plugins/pinned-rows';
```

## Built-in Aggregation Functions

| Function | Description |
|----------|-------------|
| `sum` | Sum of values |
| `avg` | Average of values |
| `count` | Count of rows |
| `min` | Minimum value |
| `max` | Maximum value |

## CSS Custom Properties

| Property | Default | Description |
|----------|---------|-------------|
| `--tbw-pinned-rows-bg` | `var(--tbw-color-panel-bg)` | Status bar background |
| `--tbw-pinned-rows-border` | `var(--tbw-color-border)` | Status bar border |

## [Configuration Options](/grid/plugins/pinned-rows/interfaces/pinnedrowsconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `slots?` | <code><a href="/grid/plugins/pinned-rows/types/pinnedrowslot/">PinnedRowSlot</a>[]</code> | Unified ordered list of pinned-row slots. When provided, `aggregationRows`, `customPanels`, `position`, `showRowCount`, `showSelectedCount` and `showFilteredCount` are ignored — slots are rendered in declared order within their `position` ('top' or 'bottom', default 'bottom'). |
| `position?` | <code><a href="/grid/plugins/pinned-rows/types/pinnedrowsposition/">PinnedRowsPosition</a></code> | Position of the info bar (default: 'bottom'). |
| `showRowCount?` | <code>boolean</code> | Show total row count in info bar (default: true). |
| `showSelectedCount?` | <code>boolean</code> | Show selected row count in info bar (default: true). |
| `showFilteredCount?` | <code>boolean</code> | Show filtered row count when filter is active (default: true). |
| `customPanels?` | <code><a href="/grid/plugins/pinned-rows/interfaces/pinnedrowspanel/">PinnedRowsPanel</a>[]</code> | Custom panels to display in the info bar. |
| `aggregationRows?` | <code><a href="/grid/plugins/pinned-rows/interfaces/aggregationrowconfig/">AggregationRowConfig</a>[]</code> | Aggregation rows (footer/header rows with computed values). |
| `fullWidth?` | <code>boolean</code> | Default fullWidth mode for all aggregation rows. When true, each aggregation row renders as a single spanning cell with label and aggregated values inline. When false (default), rows render per-column cells aligned to the grid template. Individual `AggregationRowConfig.fullWidth` (or `AggregationSlot.fullWidth`) overrides this. |

## Example

### Status Bar with Aggregation

```ts
import '@toolbox-web/grid';
import {
  PinnedRowsPlugin,
  rowCountPanel,
} from '@toolbox-web/grid/plugins/pinned-rows';

grid.gridConfig = {
  columns: [
    { field: 'product', header: 'Product' },
    { field: 'quantity', header: 'Qty', type: 'number' },
    { field: 'price', header: 'Price', type: 'currency' },
  ],
  plugins: [
    new PinnedRowsPlugin({
      slots: [
        {
          id: 'totals',
          position: 'bottom',
          aggregators: { quantity: 'sum', price: 'sum' },
          cells: { product: 'Totals:' },
        },
        { id: 'count', position: 'bottom', render: rowCountPanel() },
      ],
    }),
  ],
};
```

## See Also

- [`PinnedRowsConfig`](/grid/plugins/pinned-rows/interfaces/pinnedrowsconfig.md) for all configuration options
- [`AggregationRowConfig`](/grid/plugins/pinned-rows/interfaces/aggregationrowconfig.md) for aggregation row 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

### refresh()

Refresh the status bar to reflect current grid state.

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

***

### getContext()

Get the current status bar context.

```ts
getContext(): PinnedRowsContext
```

#### Returns

`PinnedRowsContext` - The context with row counts and other info

***

### addPanel()

Add a custom panel to the info bar.

```ts
addPanel(panel: PinnedRowsPanel): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `panel` | <code><a href="/grid/plugins/pinned-rows/interfaces/pinnedrowspanel/">PinnedRowsPanel</a></code> | The panel configuration to add |

***

### removePanel()

Remove a custom panel by ID.

```ts
removePanel(id: string): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | <code>string</code> | The panel ID to remove |

***

### addAggregationRow()

Add an aggregation row.

```ts
addAggregationRow(row: AggregationRowConfig): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `row` | <code><a href="/grid/plugins/pinned-rows/interfaces/aggregationrowconfig/">AggregationRowConfig</a></code> | The aggregation row configuration |

***

### removeAggregationRow()

Remove an aggregation row by ID.

```ts
removeAggregationRow(id: string): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | <code>string</code> | The aggregation row ID to remove |

***