# @toolbox-web/grid — Full Documentation (Angular)

> A high-performance, framework-agnostic data grid built with pure TypeScript and native Web Components. Zero runtime dependencies.

This is the **Angular-scoped** variant of `llms-full.txt`: code
examples are narrowed to Angular and the other framework adapters'
pages are omitted, so the corpus is smaller and free of irrelevant variants. For
the complete cross-framework corpus, see `llms-full.txt`; for the curated link
index, see `llms.txt`. The exhaustive per-symbol TypeDoc API is linked (not
inlined) at the end; fetch any symbol by appending `.md` to its page URL.

---

# Introduction

> A high-performance, framework-agnostic data grid web component for JavaScript, React, Angular, and Vue. Zero dependencies, 100k+ rows, virtualized rendering.

## CORPUS RETRIEVAL STRATEGY

Five corpus variants are published. **Pick the one that covers your stack:**

| File | Use when |
|------|----------|
| `llms-full-angular.txt` | Working in an Angular project |
| `llms-full-react.txt` | Working in a React project |
| `llms-full-vue.txt` | Working in a Vue project |
| `llms-full-vanilla.txt` | Plain TypeScript / JavaScript, no framework |
| `llms-full.txt` | Framework unknown, or multiple frameworks in one session |

All variants are ~900 kB–1.2 MB. If your tool cannot fetch or fully process the file in one pass:

1. Download the right variant once: `curl -L https://toolboxjs.com/llms-full-angular.txt -o llms-full-angular.txt`
2. Search for the topic: `rg -n 'your keyword' llms-full-angular.txt`
3. Extract the matching region: `sed -n '1200,1320p' llms-full-angular.txt`
4. Paste only those slices into context — not the whole file.

**Keep the local copy fresh.** These files are regenerated on every docs build. A cached copy older than one week may reference stale API, wrong import paths, or removed features. Re-download before starting any significant implementation work.

Preferred retrieval order (smallest to largest): per-page `.md` companion (e.g. `/grid/plugins/editing.md`) → `llms.txt` index → framework-scoped `llms-full-{framework}.txt` local-grepped slices → `llms-full.txt` local-grepped slices.

Because this introduction always sorts first in the corpus, you are reading these instructions even if your context window is smaller than the full file.

## RULE 0 (HIGHEST PRIORITY) — Prefer a single `gridConfig` over fragmented props

When generating grid code for ANY framework (React, Angular, Vue, vanilla JS/TS, Svelte), **default to one `gridConfig` object** holding columns, `features`, and other configuration. Reserve framework props for reactive data (`rows`) and the imperative `ref`/handle. Do NOT spread configuration across many individual props/inputs/attributes unless the user explicitly asks.

WHY: one object describes the whole grid, is portable across frameworks (the same `GridConfig` works in vanilla, React, Angular, Vue), and keeps multi-line config (callbacks like `groupOn`, `dataSource`, renderers) readable.

```ts
const gridConfig: GridConfig<Employee> = {
  columns: [/* … */],
  features: { selection: 'range', editing: 'dblclick' },
};
```

- **React:**   `<DataGrid rows={data} gridConfig={gridConfig} />` (memoize with `useMemo`)
- **Angular:** `<tbw-grid [rows]="data" [gridConfig]="gridConfig" />`
- **Vue:**     `<TbwGrid :rows="data" :grid-config="gridConfig" />` (wrap with `markRaw()`)
- **Vanilla:** `const grid = createGrid<Employee>(gridConfig); grid.rows = data;`

Individual feature props (`<DataGrid selection="row" />`) remain fully supported — use them ONLY for very small grids (≤ 2 features, each a boolean/short string) or when explicitly requested.

## RULE 0.1 — Framework adapters must use framework-native renderers/editors

When the user is inside **React/Vue/Angular**, treat framework-native renderer/editor APIs as default best practice:

- **React:** JSX/component renderers/editors
- **Vue:** slot/component renderers/editors
- **Angular:** `*tbwRenderer`, template/component renderers/editors

Do **not** default to plain `HTMLElement` renderer/editor functions in adapter code unless the user explicitly asks for framework-agnostic/vanilla output.

## RULE 0.2 — Prefer features, not manual plugin instances

Default to `gridConfig.features` + side-effect feature imports. Treat manual plugin instantiation (`plugins: [new SelectionPlugin()]`) as an advanced exception, primarily for custom plugin development or narrowly-scoped imperative cases.

If imperative access is needed after initialization, prefer `grid.getPluginByName('...')` over storing manually-created plugin instances in application code.

## CRITICAL RULES — read before generating any code

These apply to ALL frameworks. Violating them produces broken grids.

1. **Side-effect imports are always required.** `gridConfig.features.X` (or a feature prop) does NOT remove the need to import the feature factory — without the import the merge produces no plugin:
   ```ts
   import '@toolbox-web/grid/features/selection';        // vanilla / any framework
   import '@toolbox-web/grid-react/features/selection';  // or the adapter path
   ```
   Vanilla JS must also register the element itself: `import '@toolbox-web/grid';` (adapters auto-import it).
2. **Height is required.** The grid needs an explicit height or it renders at zero height: `tbw-grid { height: 400px; }`. (`display: block` is set automatically — do not add it.)
3. **Editing is opt-in.** `editable: true` on a column WITHOUT the editing feature/plugin throws. Load `@toolbox-web/grid/features/editing` and set `features: { editing: true }`.
4. **Plugin load order matters when using plugin API directly.** `ClipboardPlugin` requires `SelectionPlugin`; `UndoRedoPlugin` requires `EditingPlugin` — load the dependency first. Prefer `features` so ordering/dependencies are handled automatically.
5. **Some plugins are mutually exclusive.** `GroupingRows` ✗ `Tree` ✗ `Pivot` (all rewrite the row model); `ServerSide` ✗ `Pivot`. A dev-mode warning fires on conflict. (`ServerSide` + `Tree` and `ServerSide` + `GroupingRows` DO coexist.)
6. **Light DOM, no Shadow DOM.** CSS cascade works normally — no `::part()`/`::slotted()`.
7. **Em-based sizing.** All dimensions use `em`; scale the whole grid by changing `font-size` on `tbw-grid`.
8. **Type import:** `import type { DataGridElement } from '@toolbox-web/grid';` (the old `GridElement` alias is deprecated).

## ANTI-PATTERNS — don't reach for a plugin first

- **Don't add `SelectionPlugin` just to make a row clickable.** For "click row → open detail", listen for `cell-activate` (fires for pointer AND keyboard, so it's accessible for free). Add `SelectionPlugin` only for persistent visible selection state, checkboxes, or multi-select.
- **Don't write `cell-click`/`row-click` when you mean "activate".** Those are pointer-only — keyboard users won't trigger them. `cell-activate` is the unified, cancelable activation event. Use `cell-click` only when you specifically need pointer-only behaviour (e.g. left-vs-right button).
- **Don't subclass `BaseGridEditor` before trying `column.type`.** Built-in types (`'select'`, `'number'`, `'date'`, …) plus `gridConfig.typeDefaults` cover most editor needs. Subclass only for genuinely custom editor UI.
- **Don't reinvent post-render orchestration.** To act after first render (focus a cell, scroll to row, begin an edit), `await grid.ready()` instead of chaining `setTimeout`/`requestAnimationFrame`/`afterNextRender`.

A **high-performance, framework-agnostic data grid** web component built with pure TypeScript. No runtime dependencies—just drop it into any project and start rendering data.

## Quick Start

The grid ships as a standard custom element. Pick the install style that matches your setup.

#### With a bundler (Vite, webpack, etc.)

```bash
npm install @toolbox-web/grid
```

```typescript title="main.ts"
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.columns = [
  { field: 'id', header: 'ID', type: 'number', sortable: true },
  { field: 'name', header: 'Name', sortable: true },
  { field: 'email', header: 'Email' },
];
grid.rows = [
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  { id: 2, name: 'Bob',   email: 'bob@example.com' },
  { id: 3, name: 'Carol', email: 'carol@example.com' },
];
```

```html title="index.html"
<tbw-grid style="height: 300px;"></tbw-grid>
```

#### No build (CDN, single HTML file)

Drop one `<script>` tag and you're done — no bundler, no install. Everything is exposed on the global `TbwGrid` object.

```html title="index.html"
<!DOCTYPE html>
<script src="https://unpkg.com/@toolbox-web/grid/umd/grid.umd.js"></script>

<tbw-grid id="my-grid" style="height: 300px;"></tbw-grid>

<script>
  const grid = TbwGrid.queryGrid('#my-grid');
  grid.columns = [
    { field: 'id', header: 'ID', type: 'number', sortable: true },
    { field: 'name', header: 'Name', sortable: true },
    { field: 'email', header: 'Email' },
  ];
  grid.rows = [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob',   email: 'bob@example.com' },
    { id: 3, name: 'Carol', email: 'carol@example.com' },
  ];
</script>
```

See the [Getting Started guide](/grid/getting-started.md) for framework integration (React, Vue, Angular), declarative HTML, plugins, and TypeScript setup.

### Live Demo

```ts
// IntroBasicDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  const grid = queryGrid('#demo-intro-basic');
  if (grid) {
    grid.columns = [
      { field: 'id', header: 'ID', type: 'number', sortable: true },
      { field: 'name', header: 'Name', sortable: true },
      { field: 'email', header: 'Email' },
    ];
    grid.rows = [
      { id: 1, name: 'Alice', email: 'alice@example.com' },
      { id: 2, name: 'Bob', email: 'bob@example.com' },
      { id: 3, name: 'Carol', email: 'carol@example.com' },
      { id: 4, name: 'Dan', email: 'dan@example.com' },
      { id: 5, name: 'Eve', email: 'eve@example.com' },
    ];
  }
```

## Architecture Highlights

Under the hood, the grid employs patterns typically found in enterprise-grade solutions:

| Pattern | What It Does |
| ------- | ------------ |
| **Centralized Render Scheduler** | Batches all updates into a single `requestAnimationFrame` per frame—no layout thrashing |
| **Phase-Based Execution** | Prioritizes work (config → rows → columns → render) for predictable updates |
| **DOM Recycling** | Reuses row elements via a pool with epoch-based invalidation—minimal GC pressure |
| **Template Cloning** | Pre-created templates cloned via `cloneNode(true)`—3-4x faster than `createElement` |
| **Event Delegation** | Single listener per event type on the container—scales to any dataset size |
| **Faux Scrollbar** | Separates scroll container from content—no reflow during scroll |

Read the full [Architecture deep-dive](/grid/architecture.md) for implementation details.

## Plugin System

The core grid is intentionally minimal. Advanced features are delivered through tree-shakeable plugins — import only what you need:

- **SelectionPlugin** — Cell, row, or range selection
- **FilteringPlugin** — Column header filters with custom panels
- **EditingPlugin** — Inline editing with built-in and custom editors
- **GroupingRowsPlugin** — Hierarchical row grouping with aggregations
- **TreePlugin** — Expandable tree data with lazy loading
- **MasterDetailPlugin** — Expandable detail rows
- **ExportPlugin** — CSV, Excel, or JSON export
- **ClipboardPlugin** — Copy/paste with Excel-compatible formatting
- ...and [many more](/grid/plugins.md)

Plugins benefit from **dependency validation**, **type-safe config extension**, **auto-cleanup** via `AbortSignal`, and a **third-party friendly** API so you can [build and distribute your own](/grid/plugin-development/custom-plugins.md).

## Next Steps

Ready to dive in?

  - [Getting Started](/grid/getting-started.md): Detailed setup for Vanilla JS, React, Vue, and Angular
  - [Core Features](/grid/core.md): Sorting, rendering, keyboard navigation, and interactive playground
  - [Plugins](/grid/plugins.md): Extend with selection, filtering, grouping, and 24+ more
  - [API Reference](/grid/api-reference.md): Complete property, method, and event reference

---

---

# Getting Started

> Install @toolbox-web/grid and render your first grid in under a minute. Covers npm, CDN, ES modules, declarative HTML, and full framework integration for Vanilla JS, React, Vue, and Angular.

**Using a framework?** Jump directly to [Angular](/grid/angular/getting-started.md), [React](/grid/react/getting-started.md), or [Vue](/grid/vue/getting-started.md).

## Quick Start

1. **Install the package**

#### npm

     ```bash
     npm install @toolbox-web/grid
     ```

#### yarn

     ```bash
     yarn add @toolbox-web/grid
     ```

#### pnpm

     ```bash
     pnpm add @toolbox-web/grid
     ```

#### bun

     ```bash
     bun add @toolbox-web/grid
     ```

#### CDN

     For quick prototyping, use the UMD bundle directly:
     ```html
     <script src="https://unpkg.com/@toolbox-web/grid/umd/grid.umd.js"></script>
     ```

2. **Import and use**

   ```typescript
   import '@toolbox-web/grid';                       // registers <tbw-grid>
   import { queryGrid } from '@toolbox-web/grid';     // typed DOM helper
   ```

3. **Add the grid to your HTML**

   ```html
   <tbw-grid id="my-grid" style="height: 400px;"></tbw-grid>
   ```

:::caution[The grid needs a height]
Set a height via CSS or inline style (e.g., `height: 400px`). Without it, the grid collapses to zero height and nothing will render. Use `height: auto` if you don't want virtual scrolling.

**Tip:** A parent CSS Grid or Flexbox layout that stretches the grid (e.g., a flex child with `flex: 1` or a grid row sized with `1fr`) also counts as a height — you don't need to set one explicitly on `<tbw-grid>` itself.
:::

### Declarative Columns (No JavaScript)

Define columns directly in HTML — great for static layouts and quick prototyping:

```html
<tbw-grid style="height: 400px;">
  <tbw-grid-column field="id" header="ID" type="number" sortable></tbw-grid-column>
  <tbw-grid-column field="name" header="Name"></tbw-grid-column>
  <tbw-grid-column field="email" header="Email"></tbw-grid-column>
</tbw-grid>
```

Set `rows` from JavaScript or via the `rows` HTML attribute (JSON). See [Light DOM Columns](/grid/core.md#light-dom-columns) for the full attribute reference.

### Auto-Inferred Columns

Skip column configuration entirely — the grid creates columns from your data:

```typescript
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('#my-grid');
grid.rows = [
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com', active: true },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com', active: false },
];
// → Creates ID, Name, Email, and Active columns automatically
```

The grid detects types (`number`, `boolean`, `date`, `string`) from values and formats headers from field names (`firstName` → `First Name`). See [Column Inference](/grid/core.md#column-inference) for details.

## Framework Integration

The grid is a standard web component that works in any JavaScript environment — you can always use the Vanilla JS approach in any framework. For React, Vue, and Angular, we also provide dedicated adapter packages that enable custom component renderers and editors.

:::tip[Prefer a single `gridConfig` object]
Across every framework, the recommended pattern is to describe the grid with one `gridConfig` object — columns, `features`, and `plugins` together — and pass it as a single prop/input/attribute. Keep reactive data (`rows`) separate, since it changes independently of configuration.

A single config object is portable (the same `GridConfig` works in vanilla, React, Angular, and Vue), easy to share or snapshot in tests, and keeps multi-line feature config readable. Individual feature props (e.g. `selection="row"`) remain fully supported and are a fine shorthand for very small grids — but default to `gridConfig` for everything else, including any column that uses a custom renderer or editor.

For framework adapters (React/Vue/Angular), the default should be `gridConfig.features` rather than wiring many feature props/inputs/directives in templates. Keep those template-level bindings as shorthand for tiny examples.
:::

#### Angular

For Angular projects, use the `@toolbox-web/grid-angular` adapter package for enhanced integration:

```bash
# Install both packages
npm install @toolbox-web/grid @toolbox-web/grid-angular
```

```typescript title="grid.component.ts"
import '@toolbox-web/grid';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="employees"
      [columns]="columns"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class EmployeeGridComponent {
  employees = [
    { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
    { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
    { id: 3, name: 'Carol White', email: 'carol@example.com' },
  ];

  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ];
}
```

That's a working grid. From here, add features as you need them — each is a one-line import plus an input binding:

```typescript title="grid.component.ts (with features)"
import { GridEditingDirective } from '@toolbox-web/grid-angular/features/editing';
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import '@toolbox-web/grid';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig, CellCommitDetail } from '@toolbox-web/grid';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid, GridEditingDirective, GridSelectionDirective, GridFilteringDirective],
  template: `
    <tbw-grid
      [rows]="employees"
      [columns]="columns"
      [editing]="'dblclick'"
      [selection]="'row'"
      [filtering]="true"
      (cellCommit)="onCellCommit($event)"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class EmployeeGridComponent {
  employees = [
    { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
    { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
    { id: 3, name: 'Carol White', email: 'carol@example.com' },
  ];

  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name', editable: true },
    { field: 'email', header: 'Email', editable: true },
  ];

  // camelCase outputs deliver the unwrapped detail directly ($event is the
  // detail, not the native CustomEvent). Bind kebab-case (cell-commit) instead
  // if you need the CustomEvent for event.preventDefault().
  onCellCommit(detail: CellCommitDetail) {
    console.log('Edited:', detail);
  }
}
```

The adapter adds structural directives (`*tbwRenderer`, `*tbwEditor`), template-driven renderers/editors, and grid-level event outputs.

See the [Angular adapter docs](/grid/angular/getting-started.md) for custom renderers, editors, and the complete API reference.

## Plain JavaScript (No Build Step)

Don't use TypeScript or a bundler? The grid works with a single `<script>` tag using the UMD bundle.
Everything is available on the global `TbwGrid` object:

```html title="index.html"
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@toolbox-web/grid/umd/grid.umd.js"></script>
</head>
<body>
  <tbw-grid id="my-grid" style="height: 400px;"></tbw-grid>
  <script>
    var grid = TbwGrid.queryGrid('#my-grid');

    grid.columns = [
      { field: 'id', header: 'ID', type: 'number' },
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
    ];

    grid.rows = [
      { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
      { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
      { id: 3, name: 'Carol White', email: 'carol@example.com' },
    ];
  </script>
</body>
</html>
```

To add plugins, use the all-in-one bundle and configure via `gridConfig`:

```html title="index.html (with plugins)"
<script src="https://unpkg.com/@toolbox-web/grid/umd/grid.all.umd.js"></script>
<script>
  var grid = TbwGrid.queryGrid('#my-grid');

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number' },
      { field: 'name', header: 'Name', editable: true },
      { field: 'email', header: 'Email', editable: true },
    ],
    plugins: [
      new TbwGrid.EditingPlugin({ trigger: 'dblclick' }),
      new TbwGrid.SelectionPlugin({ mode: 'row' }),
      new TbwGrid.FilteringPlugin(),
    ],
  };

  grid.rows = [
    { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
    { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
    { id: 3, name: 'Carol White', email: 'carol@example.com' },
  ];
</script>
```

:::tip
`grid.umd.js` includes core only (~168 kB raw, ~48 kB gzipped). `grid.all.umd.js` bundles core + all plugins (~514 kB raw, ~136 kB gzipped).
You can also load individual plugin UMD files (e.g. `selection.umd.js`) for finer control over bundle size.
:::

## TypeScript Support

The package ships with full type definitions. Use generics on `queryGrid` to get typed row data throughout your code:

```typescript
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import type { ColumnConfig } from '@toolbox-web/grid';

interface Employee {
  id: number;
  name: string;
  email: string;
}

const grid = queryGrid<Employee>('tbw-grid');

// Column config is type-checked against Employee
const columns: ColumnConfig<Employee>[] = [
  { field: 'id', header: 'ID', type: 'number' },
  { field: 'name', header: 'Name' },
  // { field: 'typo' } ← TypeScript error!
];

// Event payloads are typed too
grid.on('cell-commit', ({ row, field, value }) => {
  console.log(row.name, field, value); // row is Employee
});
```

## Next Steps

Now that you have the grid set up, explore:

  - [Core Features](/grid/core.md): Sorting, editing, keyboard navigation, and interactive playground
  - [Selection Plugin](/grid/plugins/selection.md): Add row, cell, or range selection
  - [Theming](/grid/guides/theming.md): Customize colors, spacing, and typography
  - [API Reference](/grid/api-reference.md): Complete property, method, and event reference

---

# Core Features

> Interactive playground, configuration, rendering, loading states, variable row heights, events, methods, and more for @toolbox-web/grid.

This page documents built-in grid features that don't require plugins — the interactive playground, column configuration, data formatting, styling, loading states, events, methods, and more.

---

## Basic Usage

### Interactive Playground

Experiment with the grid's core options in real time. Adjust the row count, toggle columns, change the fit mode, and enable or disable sortable/resizable columns.

```ts
// InteractivePlaygroundDemo.astro
  import '@toolbox-web/grid';
import type { ColumnConfig, FitMode } from '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/editing';

  type ColumnKey = 'id' | 'name' | 'active' | 'score' | 'created' | 'role';

  const container = document.getElementById('interactive-playground-demo');
  const grid = queryGrid('tbw-grid', container!);

  if (container && grid) {
    const allColumnDefs: Record<ColumnKey, ColumnConfig> = {
      id: { field: 'id', header: 'ID', type: 'number', sortable: true, resizable: true },
      name: { field: 'name', header: 'Name', sortable: true, resizable: true },
      active: { field: 'active', header: 'Active', type: 'boolean', sortable: true },
      score: { field: 'score', header: 'Score', type: 'number', sortable: true, resizable: true },
      created: {
        field: 'created', header: 'Created', type: 'date', sortable: true, resizable: true,
      },
      role: {
        field: 'role', header: 'Role', type: 'select', sortable: true,
        options: [
          { label: 'Admin', value: 'admin' },
          { label: 'User', value: 'user' },
          { label: 'Guest', value: 'guest' },
        ],
      },
    };

    function generateRows(count: number) {
      const roles = ['admin', 'user', 'guest'];
      const names = ['Alice', 'Bob', 'Carol', 'Dan', 'Eve', 'Frank', 'Grace', 'Henry'];
      const rows: Record<string, unknown>[] = [];
      for (let i = 0; i < count; i++) {
        rows.push({
          id: i + 1,
          name: names[i % names.length] + ' ' + (Math.floor(i / names.length) + 1),
          active: i % 3 !== 0,
          score: Math.floor(Math.random() * 100),
          created: new Date(Date.now() - i * 86400000),
          role: roles[i % roles.length],
        });
      }
      return rows;
    }

    let state = {
      rowCount: 100,
      columns: ['id', 'name', 'active', 'score', 'created', 'role'] as ColumnKey[],
      fitMode: 'stretch' as FitMode,
      sortable: true,
      resizable: true,
    };

    function rebuild() {
      const columns = state.columns.map((key) => ({
        ...allColumnDefs[key],
        sortable: state.sortable,
        resizable: state.resizable,
      }));

      grid.fitMode = state.fitMode;
      grid.gridConfig = {
        columns,
        sortable: state.sortable,
        resizable: state.resizable,
        typeDefaults: {
          date: {
            format: (val: Date) =>
              val.toLocaleDateString(undefined, { day: '2-digit', month: '2-digit', year: 'numeric' }),
          },
        },
        features: { editing: 'dblclick' },
      };
      grid.rows = generateRows(state.rowCount);
    }

    // Initial render
    rebuild();

    // Re-render on control change
    container.addEventListener('control-change', ((e: CustomEvent) => {
      const { allValues } = e.detail;
      state = {
        rowCount: allValues.rowCount as number,
        columns: (allValues.columns as ColumnKey[]) ?? state.columns,
        fitMode: (allValues.fitMode as FitMode) ?? state.fitMode,
        sortable: allValues.sortable as boolean,
        resizable: allValues.resizable as boolean,
      };
      rebuild();
    }) as EventListener);
  }
```

### Keyboard Navigation

The grid implements [ARIA grid keyboard patterns](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) out of the box — no configuration required:

| Key | Action |
|-----|--------|
| <kbd>↑</kbd> <kbd>↓</kbd> <kbd>←</kbd> <kbd>→</kbd> | Move between cells |
| <kbd>Home</kbd> / <kbd>End</kbd> | Jump to first/last cell in row |
| <kbd>Ctrl</kbd> + <kbd>Home</kbd> / <kbd>Ctrl</kbd> + <kbd>End</kbd> | Jump to first/last cell in grid |
| <kbd>PgUp</kbd> / <kbd>PgDn</kbd> | Scroll by viewport height |
| <kbd>↵ Enter</kbd> | Start editing (with EditingPlugin) |
| <kbd>Esc</kbd> | Cancel editing |
| <kbd>⇥ Tab</kbd> / <kbd>⇧ Shift</kbd> + <kbd>⇥ Tab</kbd> | Move to next/previous editable cell |

For the full keyboard shortcut reference, see the [Accessibility guide](/grid/guides/accessibility.md).

### RTL (Right-to-Left) Support

The grid fully supports RTL languages like Hebrew, Arabic, and Persian. Set `dir="rtl"` on the grid or any ancestor element — keyboard navigation, column pinning, and layout all adapt automatically.

```html
<tbw-grid dir="rtl"></tbw-grid>
```

```ts
// RtlDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  const container = document.getElementById('rtl-demo-container');
  const grid = queryGrid('#demo-rtl');
  if (container && grid) {
    grid.columns = [
      { field: 'name', header: 'الاسم', width: 150 },
      { field: 'department', header: 'القسم', width: 130 },
      { field: 'salary', header: 'الراتب', width: 120, formatter: (v: number) => `${v.toLocaleString('ar-EG')} ر.س` },
    ];
    grid.rows = [
      { name: 'أحمد', department: 'الهندسة', salary: 42000 },
      { name: 'فاطمة', department: 'التصميم', salary: 38000 },
      { name: 'خالد', department: 'المبيعات', salary: 35000 },
      { name: 'سارة', department: 'الهندسة', salary: 44000 },
      { name: 'محمد', department: 'الدعم', salary: 31000 },
    ];

    container.addEventListener('control-change', ((e: CustomEvent) => {
      grid.dir = e.detail.allValues.rtl ? 'rtl' : 'ltr';
    }) as EventListener);
  }
```

**Logical column pinning:** Use `pinned: 'start'` and `pinned: 'end'` instead of `'left'`/`'right'` for direction-independent pinning. See the [Pinned Columns plugin](/grid/plugins/pinned-columns.md) for details.

---

## Configuration

### Column Inference

**Zero-config data display** — Just pass your data and the grid figures out the rest.

When you provide `rows` without defining `columns`, the grid automatically:

- Detects fields from the first row's property names
- Infers data types (`string`, `number`, `boolean`, `date`) from actual values
- Generates human-readable headers from field names (`firstName` → `First Name`)
- Applies appropriate sorting and formatting for each type

```typescript
grid.rows = myData; // That's it!
```

```ts
// ColumnInferenceDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  const grid = queryGrid('#demo-column-inference');
  if (grid) {
    grid.rows = [
      { id: 1, firstName: 'Alice', lastName: 'Johnson', age: 32, active: true, startDate: '2022-03-15' },
      { id: 2, firstName: 'Bob', lastName: 'Smith', age: 28, active: false, startDate: '2023-01-10' },
      { id: 3, firstName: 'Carol', lastName: 'Williams', age: 45, active: true, startDate: '2021-07-22' },
      { id: 4, firstName: 'David', lastName: 'Brown', age: 36, active: true, startDate: '2020-11-05' },
      { id: 5, firstName: 'Eve', lastName: 'Davis', age: 29, active: false, startDate: '2024-02-18' },
    ];
  }
```

#### Merge mode — infer everything, customize one column

By default (`columnInference: 'auto'`), inference is **all-or-nothing**: the moment you declare a
single column, the grid renders **only** that column and skips inference entirely.

Opt into `columnInference: 'merge'` for a low-config workflow: the grid always infers the full
column set from your data, then **overlays** any explicitly provided columns matched by `field`.
Feed it data and it renders everything; if you disagree with how one column is rendered, add config
for _just that column_.

```typescript
grid.columnInference = 'merge';
grid.rows = employees; // every field renders, in data-key order
// Customize only the salary column — the rest stay inferred:
grid.columns = [{ field: 'salary', type: 'number', header: 'Salary (USD)' }];
```

Behaviour in `merge` mode:

- All data fields render in **data-key order** (from the first row), auto-typed.
- A provided column overlays **only its own field** (your config wins; inferred values such as
  `header`/`type` fill the gaps) and keeps its data position.
- A provided column for a field **absent from the data** is appended at the end as a computed
  column (e.g. an `actions` column).
- To hide a column, omit its key from the row objects (control via the data shape).

Set it via the `columnInference` prop, the `column-inference="merge"` attribute, or
`gridConfig.columnInference`. The default `'auto'` preserves the classic "declare a subset → show
only that subset" behaviour.

### Light DOM Columns

**Declarative configuration** — Define columns in HTML instead of JavaScript.

Use `<tbw-grid-column>` elements (or framework wrapper components) to declaratively define columns directly in your markup:

#### Angular

```html
<tbw-grid [rows]="rows">
  <tbw-grid-column field="id" header="ID" width="80"></tbw-grid-column>
  <tbw-grid-column field="name" header="Full Name" sortable></tbw-grid-column>
  <tbw-grid-column field="email" header="Email Address"></tbw-grid-column>
</tbw-grid>
```

This approach is ideal for:

- **Static layouts** where columns don't change at runtime
- **Server-rendered pages** where HTML is generated on the server
- **Template-driven frameworks** like Angular or Vue that prefer declarative syntax
- **Quick prototyping** without writing JavaScript

```ts
// LightDomColumnsDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  const grid = queryGrid('#demo-light-dom-columns');
  if (grid) {
    grid.rows = [
      { id: 1, name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering' },
      { id: 2, name: 'Bob Smith', email: 'bob@example.com', department: 'Sales' },
      { id: 3, name: 'Carol Williams', email: 'carol@example.com', department: 'Marketing' },
      { id: 4, name: 'David Brown', email: 'david@example.com', department: 'Engineering' },
      { id: 5, name: 'Eve Davis', email: 'eve@example.com', department: 'HR' },
    ];
  }
```

#### Initial column ordering with the `order` attribute

Use the `order` attribute to control the initial position of columns when they are first rendered. This is useful for reordering columns declaratively without JavaScript:

#### Angular

```html
<tbw-grid [rows]="rows">
  <tbw-grid-column field="id" header="ID" order="2"></tbw-grid-column>
  <tbw-grid-column field="name" header="Full Name" order="0"></tbw-grid-column>
  <tbw-grid-column field="email" header="Email Address" order="1"></tbw-grid-column>
</tbw-grid>
```

Columns without an `order` attribute keep their relative order; columns with `order` are inserted at their target indices. The `order` attribute only affects the **initial render**; user interactions (drag-to-reorder via the [Reorder plugin](/grid/plugins/reorder-columns.md)) take precedence after that. Use [`resetColumnOrder()`](/grid/api/plugins/reorder-columns/methods/resetcolumnorder/) to restore the order-attribute positioning.

**Combining with `columnInference: 'merge'`** — The `order` attribute becomes especially powerful in `merge` mode. With inference enabled, the grid automatically displays all data fields, and you can use light-DOM `<tbw-grid-column>` elements to customize **only the columns you care about** — adding a custom `header`, overriding the `type`, adjusting `width`, and positioning via `order`, all without declaring the entire column set.

### Configuration Reference

The grid is configured through the `gridConfig` property (or individual shorthand properties). The table below covers the most common options — see [`GridConfig`](/grid/api/core/interfaces/gridconfig.md) for the full, type-checked reference.

| Property | Type | Description |
|----------|------|-------------|
| `columns` | [`ColumnConfig[]`](/grid/api/core/interfaces/columnconfig.md) | Column definitions |
| `rows` | `any[]` | Row data array (top-level grid prop, not on `GridConfig`) |
| `fitMode` | [`FitMode`](/grid/api/core/types/fitmode.md) | How columns fill available width (`'stretch'` or `'fixed'`) |
| `columnInference` | [`ColumnInferenceMode`](/grid/api/core/types/columninferencemode.md) | How inference combines with provided columns (`'auto'` default, or `'merge'`) |
| `sortable` | `boolean` | Grid-wide sort toggle (default `true`) |
| `resizable` | `boolean` | Grid-wide resize toggle (default `true`) |
| `initialSort` | `{ field, direction }` | Sort applied on first render (`'asc'` or `'desc'`) |
| `rowHeight` | `number \| (row, index) => number \| undefined` | Fixed or variable row heights |
| `getRowId` | `(row) => string` | Unique row identity function |
| `rowClass` | `(row) => string \| string[]` | Dynamic row CSS classes |
| `typeDefaults` | `Record<string, `[`TypeDefault`](/grid/api/core/interfaces/typedefault.md)`>` | Default format/renderer per column `type` |
| `plugins` | [`GridPlugin[]`](/grid/api/plugin-development/interfaces/gridplugin.md) | Plugin instances |
| `features` | [`Partial<FeatureConfig>`](/grid/api/core/interfaces/featureconfig.md) | Declarative feature config (alternative to `plugins`) |
| `columnState` | [`GridColumnState`](/grid/api/core/interfaces/gridcolumnstate.md) | Saved column state to restore on init |
| `icons` | [`GridIcons`](/grid/api/core/interfaces/gridicons.md) | Grid-wide icon overrides |
| `animation` | [`AnimationConfig`](/grid/api/core/interfaces/animationconfig.md) | Animation defaults (expand/collapse, reorder, etc.) |
| `loadingRenderer` | [`LoadingRenderer`](/grid/api/core/types/loadingrenderer.md) | Custom loading indicator |
| `emptyRenderer` | [`EmptyRenderer`](/grid/api/core/types/emptyrenderer.md) ` \| null` | Custom no-rows message (set `null` to suppress) |
| `emptyOverlay` | `'rows' \| 'grid'` | Where to mount the empty overlay (default `'rows'`) |
| `sortHandler` | [`SortHandler`](/grid/api/core/types/sorthandler.md) | Low-level sort engine override (prefer `sortComparator` per-column) |
| `gridAriaLabel` | `string` | Accessible label for the grid (`aria-label`) |
| `gridAriaDescribedBy` | `string` | ID of an element that describes the grid (`aria-describedby`) |
| `a11y` | [`A11yConfig`](/grid/api/core/interfaces/a11yconfig.md) | Screen reader announcement messages and toggle |

**Precedence (low → high):**

1. `gridConfig` prop (base)
2. Light DOM elements (declarative)
3. `columns` prop (direct array)
4. Inferred columns (auto-detected from first row)
5. Individual props (`fitMode`) — highest

> In `columnInference: 'merge'` mode the order differs: the grid infers the full column set first,
> then overlays the merged provided columns by `field` (provided wins, in data-key order).

### System Columns

Some columns exist to support grid behaviour rather than to display user data — a row-action menu, a status indicator, a row number, the selection checkbox the grid injects for you. Mark any column with `utility: true` and the grid treats it as a **system column**: rendered normally, but excluded from chooser, reorder, print, export, clipboard, and selection.

```ts
{
  field: '__actions',
  header: '',
  width: 80,
  utility: true,                   // ← marks this as a system column
  resizable: false,
  sortable: false,
  filterable: false,
  viewRenderer: ({ row }) => createActionsButton(row),
}
```

**What `utility: true` does:**

| Surface | Behaviour |
| --- | --- |
| Visibility panel | Not listed — users cannot toggle it on/off |
| Column reorder | Locked in place |
| Print | Hidden by `PrintPlugin` (override with `printHidden: false`) |
| Clipboard copy | Skipped by `ClipboardPlugin` |
| Export (CSV/JSON/XLSX) | Skipped by `ExportPlugin` |
| Range / row selection | Click does not extend selection |
| Filter UI | No filter button, no filter model entry |
| Cell rendering | **Rendered normally** — your renderer runs |

> **Naming convention:** Prefix the field with `__` (e.g. `__actions`, `__status`) so it cannot collide with a real data field.

**Built-in system columns** the grid synthesises automatically use the same flag: `SelectionPlugin` checkbox (`__tbw_checkbox`), `MasterDetailPlugin` / `TreePlugin` / `GroupingRowsPlugin` expander (`__tbw_expander`), `RowDragDropPlugin` drag handle.

**Related flags** when you want finer control: `lockPosition` (reorder only), `lockVisible` (chooser only), `printHidden` (print only), `hidden` (entirely hidden).

---

## Presentation

### Value Accessors

**Resolve a cell's value when it isn't a plain field read.** By default the grid reads `row[field]`. A `valueAccessor` is only relevant when that's not the right value — typically because the cell is computed from multiple row fields, plucked from a nested structure, or derived from something outside the row.

You _could_ achieve the visual result with a custom `renderer` or `format` function alone, but you'd lose every other feature that depends on knowing what the cell's value actually is — sorting (unless you also write a `sortComparator`), filtering (unless you also write a `filterValue`), grouping, aggregations, copy-to-clipboard, and exports (CSV / Excel) would all see `undefined` or the raw `row[field]`. `valueAccessor` plugs the value in once and every consumer stays consistent.

```typescript
grid.columns = [
  // Computed from sibling fields
  {
    field: 'total',
    headerName: 'Total',
    valueAccessor: ({ row }) => row.qty * row.price,
  },

  // Pluck from a nested array
  {
    field: 'lastShipmentDate',
    headerName: 'Last Shipment',
    valueAccessor: ({ row }) => row.shipments?.find((s) => s.kind === 'BL')?.date,
    format: (v) => (v ? new Date(v).toLocaleDateString() : '—'),
  },

  // Normalize / coerce
  {
    field: 'name',
    valueAccessor: ({ row }) => `${row.firstName} ${row.lastName}`.trim(),
  },
];
```

**The accessor receives** `{ row, column, rowIndex }` and returns the column's typed value. Use it whenever the *cell value* isn't a plain field read.

#### Precedence

For each operation, the grid looks for a column-level override first, then falls back to the accessor, then to the field:

| Operation | Order |
|---|---|
| **Sort comparison** | `sortComparator` → `valueAccessor` → `row[field]` |
| **Filter value** | `filterValue` → `valueAccessor` → `row[field]` |
| **Group key & aggregations** (`sum`, `avg`, `min`, `max`, `first`, `last`) | `valueAccessor` → `row[field]` |
| **Copy / export (CSV, Excel)** | `valueAccessor` → `row[field]` (then `format` if present) |
| **Display** (`format` / `renderer`) | `valueAccessor` → `row[field]` |

This means you write the lookup logic once and every consumer stays consistent.

#### Caching & invalidation

Accessor results are cached per `(row, column.field)` in a `WeakMap` keyed on the row object — so an expensive accessor (e.g. `array.find`) runs once per row regardless of how many features read it. Primitive rows bypass the cache.

The cache is invalidated automatically when:

- A row reference changes (immutable updates — recommended pattern).
- You call `RowManager.updateRow` / `updateRows` / `applyTransaction` (in-place edits).
- The Editing plugin commits a value.

If you mutate row data outside of those paths, call `invalidateAccessorCache(row?, field?)` manually:

```typescript
import { invalidateAccessorCache } from '@toolbox-web/grid';

row.shipments.push(newShipment);
invalidateAccessorCache(row, 'lastShipmentDate'); // narrow scope
// or invalidateAccessorCache(row);                // all fields on this row
// or invalidateAccessorCache();                   // entire cache
```

:::tip[Reactive accessors (signals / refs / state)]
If your accessor closes over reactive state — an Angular `signal`, a Vue `ref`, a React store value — the cache won't notice when that state changes (the row reference is still the same). Pair the accessor with a framework-level effect that invalidates the cache and asks the grid to re-render:

#### Angular

```typescript
import { effect, inject } from '@angular/core';
import { invalidateAccessorCache } from '@toolbox-web/grid';

fxRate = signal(1.0);

columns = [{
  field: 'totalUsd',
  valueAccessor: ({ row }) => row.totalEur * this.fxRate(),
}];

constructor() {
  effect(() => {
    this.fxRate(); // tracked dependency
    invalidateAccessorCache();
    this.grid()?.requestRender();
  });
}
```

:::

#### Editing

Accessors are **read-only**. Cells driven by a `valueAccessor` cannot currently be written back through the Editing plugin (a matching `valueSetter` API is planned). For now, gate them with `editable: false` or omit `editable`.

---

### Formatters

**Transform how values are displayed** — Formatters convert raw data values into user-friendly text.

A formatter is a function that receives the cell value and returns a display string:

```typescript
grid.columns = [
  // Currency
  { field: 'salary', format: (v) => `$${v.toLocaleString()}` },

  // Date
  { field: 'hireDate', format: (v) => new Date(v).toLocaleDateString() },

  // Percentage
  { field: 'progress', format: (v) => `${(v * 100).toFixed(1)}%` },

  // Prefix
  { field: 'id', format: (v) => `#${v}` },
];
```

### Row Styling

**Style entire rows** based on data using the `rowClass` callback:

```typescript
grid.gridConfig = {
  rowClass: (row) => (row.status === 'inactive' ? 'row-inactive' : ''),
};
```

Then define the CSS class in your stylesheet:

```css
.row-inactive { opacity: 0.5; }
```

### Cell Styling

**Style individual cells** based on their value using `cellClass` on a column:

```typescript
grid.columns = [
  {
    field: 'score',
    cellClass: (value) => {
      if (value >= 90) return 'cell-success';
      if (value < 50) return 'cell-danger';
      return '';
    },
  },
];
```

:::tip
You can combine `rowClass` and `cellClass`. When styles conflict, cell styles win because cells are children of rows in the DOM hierarchy.
:::

```ts
// RowCellStylingDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  interface Employee {
    id: number;
    name: string;
    status: string;
    score: number;
    department: string;
  }

  const grid = queryGrid<Employee>('#demo-row-cell-styling');
  if (grid) {
    grid.gridConfig = {
      rowClass: (row) => row.status === 'inactive' ? 'row-inactive' : '',
      columns: [
        { field: 'id', header: 'ID', width: 60 },
        { field: 'name', header: 'Name', width: 140 },
        { field: 'department', header: 'Department', width: 120 },
        { field: 'status', header: 'Status', width: 100 },
        {
          field: 'score',
          header: 'Score',
          width: 100,
          align: 'right',
          cellClass: (value) => {
            if ((value as number) >= 90) return 'cell-success';
            if ((value as number) < 50) return 'cell-danger';
            if ((value as number) < 70) return 'cell-warning';
            return '';
          },
        },
      ],
    };
    grid.rows = [
      { id: 1, name: 'Alice', status: 'active', score: 95, department: 'Engineering' },
      { id: 2, name: 'Bob', status: 'inactive', score: 42, department: 'Sales' },
      { id: 3, name: 'Carol', status: 'active', score: 78, department: 'Marketing' },
      { id: 4, name: 'David', status: 'active', score: 35, department: 'Engineering' },
      { id: 5, name: 'Eve', status: 'active', score: 91, department: 'HR' },
      { id: 6, name: 'Frank', status: 'inactive', score: 67, department: 'Finance' },
    ];
  }
```

### Renderers

**Full control over cell content** — Renderers let you create custom HTML elements for cells.

While formatters return plain text, renderers return DOM elements. Use renderers when you need:

- **Custom components**: Checkboxes, badges, progress bars, buttons
- **Interactive elements**: Links, icons, action buttons
- **Rich formatting**: Multiple elements, images, complex layouts

#### Angular

```typescript
import { Component } from '@angular/core';
import { Grid, TbwRenderer } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, TbwRenderer],
  template: `
    <tbw-grid [rows]="rows" style="height: 400px; display: block">
      <tbw-grid-column field="status" header="Status">
        <span *tbwRenderer="let value" [class]="'badge badge-' + value">
          {{ value }}
        </span>
      </tbw-grid-column>
      <tbw-grid-column field="active" header="Active">
        <input *tbwRenderer="let value" type="checkbox" [checked]="!!value" disabled />
      </tbw-grid-column>
    </tbw-grid>
  `,
})
export class EmployeeGridComponent {
  rows = [/* ... */];
}
```

The renderer receives a [`CellRenderContext`](/grid/api/core/interfaces/cellrendercontext.md) — the cell value, the row object, the field name, and the column config.

:::note[Why no `rowIndex`?]
Renderer and editor contexts intentionally provide the **row object** instead of a row index. A `rowIndex` reflects the row's position in the grid's *current* sorted/filtered/grouped view — it silently becomes stale whenever the user sorts, filters, or reorders. The `row` object is a stable identity that remains valid regardless of view state.

If you need the visual index at a specific moment (e.g. for conditional styling of even/odd rows), derive it inside the renderer:

```typescript
renderer: (ctx) => {
  const rowIndex = grid.rows.indexOf(ctx.row);
  // Use rowIndex for one-time positional logic
}
```

For event-driven use cases, click and activation events (`cell-click`, `row-click`, `cell-activate`) already include `rowIndex` in their detail payload.
:::

```ts
// CustomRenderersDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  interface Employee {
    id: number;
    name: string;
    status: string;
    active: boolean;
    rating: number;
    salary: number;
  }

  const grid = queryGrid<Employee>('#demo-custom-renderers');
  if (grid) {
    grid.columns = [
      { field: 'id', header: 'ID', width: 60 },
      { field: 'name', header: 'Name', width: 140 },
      {
        field: 'status',
        header: 'Status',
        width: 110,
        renderer: ({ value, cellEl }) => {
          const colors: Record<string, string> = {
            active: '#16a34a', inactive: '#dc2626', 'on-leave': '#d97706',
          };
          const badge = document.createElement('span');
          badge.style.cssText = `
            display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 0.8em;
            background: ${colors[value as string] || '#888'}22; color: ${colors[value as string] || '#888'};
            font-weight: 600;
          `;
          badge.textContent = (value as string).charAt(0).toUpperCase() + (value as string).slice(1);
          return badge;
        },
      },
      {
        field: 'active',
        header: 'Active',
        width: 80,
        align: 'center',
        renderer: ({ value }) => {
          const checkbox = document.createElement('input');
          checkbox.type = 'checkbox';
          checkbox.checked = !!value;
          checkbox.disabled = true;
          return checkbox;
        },
      },
      {
        field: 'rating',
        header: 'Rating',
        width: 100,
        align: 'center',
        renderer: ({ value }) => '★'.repeat(value as number) + '☆'.repeat(5 - (value as number)),
      },
      {
        field: 'salary',
        header: 'Salary',
        width: 120,
        align: 'right',
        format: (value) => `$${(value as number).toLocaleString()}`,
      },
    ];
    grid.rows = [
      { id: 1, name: 'Alice Johnson', status: 'active', active: true, rating: 5, salary: 95000 },
      { id: 2, name: 'Bob Smith', status: 'inactive', active: false, rating: 3, salary: 72000 },
      { id: 3, name: 'Carol Williams', status: 'on-leave', active: true, rating: 4, salary: 88000 },
      { id: 4, name: 'David Brown', status: 'active', active: true, rating: 5, salary: 105000 },
      { id: 5, name: 'Eve Davis', status: 'active', active: false, rating: 2, salary: 65000 },
    ];
  }
```

#### Light DOM renderers

You can also define a cell renderer **declaratively in HTML** — no JavaScript required. Nest a
`<tbw-grid-column-view>` element inside a `<tbw-grid-column>`; its content becomes the cell template.
Use `{{ value }}` to interpolate the cell value (and `{{ row.field }}` for other row fields):

```html
<tbw-grid column-inference="merge">
  <tbw-grid-column field="status">
    <tbw-grid-column-view>
      <span class="badge badge-{{ value }}">{{ value }}</span>
    </tbw-grid-column-view>
  </tbw-grid-column>
</tbw-grid>
```

The companion light-DOM templates are `<tbw-grid-column-editor>` (custom editor, requires the
[Editing plugin](/grid/plugins/editing.md)) and `<tbw-grid-column-header>` (custom header cell). See the
[API reference](/grid/api-reference.md#column-elements) for the full list. The framework adapters
expose the same capability through their own template syntax — `#cell` slots in Vue, `*tbwRenderer`
in Angular, and `renderer` props in React (shown in the tabs above).

#### Renderer security: avoid `innerHTML`

Renderers run with full DOM access. The grid does not sandbox what you do inside one, so user-supplied data must be inserted safely. The hazard is `innerHTML`:

```typescript
// ✅ Safe — textContent escapes HTML automatically
renderer: (ctx) => {
  const span = document.createElement('span');
  span.textContent = ctx.value;
  return span;
};

// ❌ XSS vulnerability — user input rendered as HTML
renderer: (ctx) => {
  const div = document.createElement('div');
  div.innerHTML = ctx.value; // If value contains <script>, it executes
  return div;
};
```

If you genuinely need to inject HTML (e.g. rendering a server-trusted markdown snippet), sanitize first with a library like [DOMPurify](https://github.com/cure53/DOMPurify) before assigning to `innerHTML`.

:::note[String-returning renderers are auto-sanitized]
When a cell renderer or group header renderer returns an **HTML string** (rather than an `HTMLElement` / `Node` / framework component), the grid runs the string through an internal sanitizer that strips `<script>` elements and event-handler attributes (`onclick`, `onerror`, etc.) before inserting it into the DOM. This is defense-in-depth — always validate your data upstream, but accidental injection through these renderer paths will not execute. Renderers that return `HTMLElement` / `Node` / framework components are inserted as-is and are not sanitized; the `textContent` rule above is your responsibility.
:::

### Choosing: Formatter vs Renderer

Now that you've seen both, here's a quick reference for picking the right one:

| | Formatter (`format`) | Renderer (`renderer`) |
|---|---|---|
| **Returns** | String | DOM element |
| **Use for** | Currency, dates, percentages, text formatting | Checkboxes, badges, buttons, links, images |
| **Performance** | Faster (text only) | Slower (DOM creation) |
| **Interactivity** | None (display only) | Full (event listeners, components) |

**Rule of thumb:** If you only need to change how a value *looks*, use a `format` function. If you need interactive elements or custom HTML structure, use a `renderer`.

### Row Animation

The grid provides a built-in row animation API for highlighting changes, insertions, and removals with visual feedback.

| Method | Description | CSS Variable |
|--------|-------------|--------------|
| `animateRow(i, 'change')` | Flash highlight for data changes | `--tbw-row-change-duration` (500ms) |
| `insertRow(i, row)` | Slide-in animation for new rows | `--tbw-row-insert-duration` (300ms) |
| `removeRow(i)` | Fade-out animation for removed rows | `--tbw-row-remove-duration` (200ms) |
| `applyTransaction(tx)` | Animates add/update/remove in one pass | All of the above |

```typescript
// Highlight a row after updating
grid.rows[5].status = 'updated';
grid.animateRow(5, 'change');

// Animate by row ID (stable when sorted/filtered)
grid.animateRowById(data.id, 'change');

// Animate multiple rows at once
grid.animateRows([0, 2, 5], 'change');
```

**Customize appearance:**

```css
tbw-grid {
  --tbw-row-change-duration: 750ms;
  --tbw-row-change-color: rgba(34, 197, 94, 0.25);
}
```

```ts
// RowAnimationDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  interface Item { id: number; name: string; status: string; }

  const grid = queryGrid<Item>('#demo-row-animation');

  if (grid) {
    const container = document.querySelector('.grid-demo');
    let nextId = 6;
    const data: Item[] = [
      { id: 1, name: 'Alpha', status: 'active' },
      { id: 2, name: 'Bravo', status: 'active' },
      { id: 3, name: 'Charlie', status: 'pending' },
      { id: 4, name: 'Delta', status: 'active' },
      { id: 5, name: 'Echo', status: 'inactive' },
    ];

    grid.columns = [
      { field: 'id', header: 'ID', width: 60 },
      { field: 'name', header: 'Name', width: 140 },
      { field: 'status', header: 'Status', width: 120 },
    ];
    grid.rows = data;

    container.addEventListener('click', (e) => {
      const action = (e.target as HTMLElement).dataset.animAction;
      if (!action) return;

      if (action === 'change') {
        const idx = Math.floor(Math.random() * grid.rows.length);
        grid.animateRow(idx, 'change');
      } else if (action === 'insert') {
        const id = nextId++;
        const row = { id, name: `New-${id}`, status: 'new' };
        grid.insertRow(grid.rows.length, row);
      } else if (action === 'remove' && grid.rows.length > 1) {
        grid.removeRow(grid.rows.length - 1);
      }
    });
  }
```

:::note
When using the [**EditingPlugin**](/grid/plugins/editing.md), rows are automatically animated with `'change'` after a successful edit commit.
:::

### Type-Level Defaults

Define default formatters and renderers for all columns of a specific `type`:

#### Angular

```typescript
import { Component } from '@angular/core';
import { Grid, provideGridTypeDefaults } from '@toolbox-web/grid-angular';
import { CheckboxCellComponent } from './checkbox-cell.component';
import { StatusBadgeComponent } from './status-badge.component';

@Component({
  imports: [Grid],
  providers: [
    provideGridTypeDefaults({
      currency: {
        format: (value) =>
          new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value),
      },
      boolean: { renderer: CheckboxCellComponent },
      status: { renderer: StatusBadgeComponent },
    }),
  ],
  template: `
    <tbw-grid [rows]="rows" [columns]="columns" />
  `,
})
export class AppComponent {
  columns = [
    { field: 'salary', type: 'currency' },
    { field: 'active', type: 'boolean' },
    { field: 'status', type: 'status' },
  ];
}
```

Type defaults reduce repetition when many columns share the same presentation. Column-level `format` or `renderer` overrides type defaults when both are specified.

### Custom Header Renderers

Customize column header cells using `headerLabelRenderer` or `headerRenderer`.

:::tip
The framework adapters (React, Vue, Angular) bridge `headerRenderer` and `headerLabelRenderer` — you can use React JSX, Vue components/render functions, or Angular component classes just like cell renderers. Vanilla DOM functions also work.
:::

**`headerLabelRenderer`** — Modify just the label portion of the header (sort icons and filter buttons are still managed by the grid):

#### Angular

```typescript
// Using a component class in ColumnConfig
{
  field: 'name',
  header: 'Name',
  headerLabelRenderer: RequiredLabelComponent,
}

// RequiredLabelComponent
@Component({
  selector: 'app-required-label',
  template: `{{ value() }} <span style="color:red">*</span>`,
})
export class RequiredLabelComponent {
  value = input<string>();
  column = input<unknown>();
}
```

**`headerRenderer`** — Full control over the entire header cell. You are responsible for rendering sort icons using `ctx.renderSortIcon()`:

#### Angular

```typescript
// Using a component class in ColumnConfig
{
  field: 'email',
  header: 'Email',
  headerRenderer: EmailHeaderComponent,
}

// EmailHeaderComponent
@Component({
  selector: 'app-email-header',
  template: `
    <div style="display:flex;align-items:center;gap:6px;width:100%">
      <span>📧</span>
      <span style="flex:1">{{ value() }}</span>
    </div>
  `,
})
export class EmailHeaderComponent {
  value = input<string>();
  column = input<unknown>();
  sortState = input<'asc' | 'desc' | null>();
  filterActive = input<boolean>();
  renderSortIcon = input<() => HTMLElement | null>();
  renderFilterButton = input<() => HTMLElement | null>();
}
```

The [`HeaderCellContext`](/grid/api/core/interfaces/headercellcontext.md) gives you the label text, the column config, the current sort/filter state, and helpers to render the built-in sort icon and filter button when you want to keep them.

```ts
// HeaderRenderersDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  const grid = queryGrid('#demo-header-renderers');

  if (grid) {
    grid.columns = [
      { field: 'id', header: 'ID', sortable: true, width: 60 },
      {
        field: 'name',
        header: 'Name',
        sortable: true,
        resizable: true,
        headerLabelRenderer: ({ value }) => {
          const span = document.createElement('span');
          span.innerHTML = `${value} <span style="color:red;font-weight:bold;">*</span>`;
          return span;
        },
      },
      {
        field: 'email',
        header: 'Email',
        sortable: true,
        resizable: true,
        headerRenderer: (ctx) => {
          const wrapper = document.createElement('div');
          wrapper.style.cssText = 'display:flex;align-items:center;gap:6px;width:100%;';
          const icon = document.createElement('span');
          icon.textContent = '📧';
          wrapper.appendChild(icon);
          const label = document.createElement('span');
          label.textContent = ctx.value;
          label.style.flex = '1';
          wrapper.appendChild(label);
          const sortIcon = ctx.renderSortIcon();
          if (sortIcon) wrapper.appendChild(sortIcon);
          return wrapper;
        },
      },
      { field: 'score', header: 'Score', sortable: true, type: 'number', width: 80 },
    ];

    grid.rows = [
      { id: 1, name: 'Alice', email: 'alice@example.com', score: 85 },
      { id: 2, name: 'Bob', email: 'bob@example.com', score: 72 },
      { id: 3, name: 'Carol', email: 'carol@example.com', score: 91 },
      { id: 4, name: 'Dan', email: 'dan@example.com', score: 68 },
      { id: 5, name: 'Eve', email: 'eve@example.com', score: 95 },
    ];
  }
```

---

## Column State Persistence

The grid tracks column state — widths, sort direction, order, and visibility. You can save, load, and reset this state for user personalization.

### What State Contains

`getColumnState()` returns an array of [`GridColumnState`](/grid/api/core/interfaces/gridcolumnstate.md) objects — one entry per column capturing its field, current width, sort direction and priority, and visibility.

### Listening for Changes

The `column-state-change` event fires whenever the user resizes, reorders, sorts, or hides/shows columns:

#### Angular

```html
<tbw-grid [rows]="rows" (column-state-change)="onColumnStateChange($event)" />
```

```typescript
onColumnStateChange(e: CustomEvent<GridColumnState[]>) {
  localStorage.setItem('my-grid-state', JSON.stringify(e.detail));
}
```

### Applying Saved State

Restore a previously saved state using `applyColumnState()`:

```typescript
const saved = localStorage.getItem('my-grid-state');
if (saved) {
  grid.applyColumnState(JSON.parse(saved));
}
```

### Resetting State

Re-assign the original column definitions to reset to defaults:

```typescript
grid.columns = [...originalColumns];
```

```ts
// ColumnStatePersistenceDemo.astro
  import '@toolbox-web/grid';
import type { ColumnConfig, GridColumnState } from '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  const STORAGE_KEY = 'tbw-demo-column-state';

  const container = document.getElementById('demo-column-state')?.closest('.grid-demo');
  if (container) {
    const grid = queryGrid('tbw-grid', container)!;

    const status = container.querySelector<HTMLElement>('[data-status]')!;
    const log = container.querySelector<HTMLElement>('[data-log]')!;

    const defaultColumns: ColumnConfig[] = [
      { field: 'id', header: 'ID', width: 60 },
      { field: 'name', header: 'Name', width: 160 },
      { field: 'department', header: 'Department', width: 140 },
      { field: 'salary', header: 'Salary', type: 'number', width: 100 },
      { field: 'location', header: 'Location', width: 130 },
    ];

    grid.columns = defaultColumns;
    grid.sortable = true;
    grid.resizable = true;
    grid.rows = [
      { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, location: 'New York' },
      { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 72000, location: 'London' },
      { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 108000, location: 'Berlin' },
      { id: 4, name: 'Dan Brown', department: 'Sales', salary: 67000, location: 'Tokyo' },
      { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 81000, location: 'New York' },
      { id: 6, name: 'Frank Miller', department: 'Sales', salary: 73000, location: 'London' },
    ];

    function showStatus(msg: string) {
      status.textContent = msg;
      setTimeout(() => { status.textContent = ''; }, 2000);
    }

    function appendLog(msg: string) {
      log.textContent += msg + '\n';
      log.scrollTop = log.scrollHeight;
    }

    grid.on('column-state-change', (detail) => {
      appendLog(`State changed: ${JSON.stringify(detail).slice(0, 120)}…`);
    });

    container.querySelector('[data-save]')!.addEventListener('click', () => {
      const state = grid.getColumnState();
      localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
      showStatus('State saved!');
      appendLog('Saved: ' + JSON.stringify(state, null, 2));
    });

    container.querySelector('[data-load]')!.addEventListener('click', () => {
      const raw = localStorage.getItem(STORAGE_KEY);
      if (!raw) { showStatus('No saved state found.'); return; }
      const state: GridColumnState[] = JSON.parse(raw);
      grid.applyColumnState(state);
      showStatus('State loaded!');
      appendLog('Loaded: ' + JSON.stringify(state, null, 2));
    });

    container.querySelector('[data-clear]')!.addEventListener('click', () => {
      localStorage.removeItem(STORAGE_KEY);
      showStatus('Saved state cleared.');
      appendLog('Cleared localStorage.');
    });

    container.querySelector('[data-reset]')!.addEventListener('click', () => {
      grid.columns = [...defaultColumns];
      showStatus('Grid reset to defaults.');
      appendLog('Reset to default columns.');
    });
  }
```

---

## Shell Components

:::caution[The shell moved to a plugin]
The shell (header bar, toolbar, and tool-panel sidebar) is **no longer part of core** — it is now the **[Shell plugin](/grid/plugins/shell.md)**. See that page for the full guide, demos, and configuration reference.

In **v2.x** the shell is **auto-registered**, so existing code keeps working without an import. That implicit auto-registration is **deprecated**: from **v3.0.0** the shell is opt-in — code that uses the header bar, toolbar, or tool panels **MUST** enable it explicitly:

```ts
import '@toolbox-web/grid/features/shell';

grid.gridConfig = {
  features: { shell: { header: { title: 'Employee Data' } } },
};
```

The `grid.register*` / `openToolPanel` element delegates — and importing shell types from `@toolbox-web/grid` instead of `@toolbox-web/grid/plugins/shell` — are **deprecated** and removed at v3. The `shell` configuration object itself is augmented onto `gridConfig` by the plugin and is **not** deprecated. See [Migrating to the feature API](/grid/plugins/shell.md#migrating-to-the-feature-api).
:::

---

## Loading States

The grid supports loading indicators at three levels: grid-wide, per-row, and per-cell.

### API Reference

**Grid-level** — Shows a full overlay spinner:

```typescript
grid.loading = true;
// ... fetch data ...
grid.loading = false;
```

The `loading` attribute also works in HTML: `<tbw-grid loading></tbw-grid>`.

**Row-level** — Shows a spinner on a specific row (requires `getRowId`):

```typescript
grid.setRowLoading('row-42', true);
// ... update row ...
grid.setRowLoading('row-42', false);
```

**Cell-level** — Shows a spinner on a specific cell:

```typescript
grid.setCellLoading('row-42', 'status', true);
// ... update cell ...
grid.setCellLoading('row-42', 'status', false);
```

**Query and clear:**

```typescript
grid.isRowLoading('row-42');          // boolean
grid.isCellLoading('row-42', 'name'); // boolean
grid.clearAllLoading();               // remove all indicators
```

```ts
// LoadingStatesDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  interface Employee { id: string; name: string; email: string; department: string; }

  const container = document.getElementById('loading-states-container');
  const grid = queryGrid<Employee>('tbw-grid', container!);

  if (container && grid) {
    const names = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Henry'];
    const departments = ['Engineering', 'Sales', 'Marketing', 'HR', 'Finance'];
    const employees: Employee[] = Array.from({ length: 8 }, (_, i) => ({
      id: `emp-${i + 1}`,
      name: `${names[i % names.length]} ${i + 1}`,
      email: `${names[i % names.length].toLowerCase()}${i + 1}@example.com`,
      department: departments[i % departments.length],
    }));

    grid.gridConfig = { getRowId: (row) => row.id };
    grid.columns = [
      { field: 'id', header: 'ID', width: 80 },
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
      { field: 'department', header: 'Department' },
    ];
    grid.rows = employees;

    const hints: Record<string, string> = {
      grid: 'Click <strong>▶ Simulate</strong> to show full-grid loading overlay.',
      row: 'Click any <strong>row</strong> to trigger row loading.',
      cell: 'Click any <strong>cell</strong> to trigger cell loading.',
    };
    const hintEl = container.querySelector('.loading-hint');

    let currentMode: 'grid' | 'row' | 'cell' = 'grid';
    let currentAutoReset = true;

    container.addEventListener('control-change', ((e: CustomEvent) => {
      const v = e.detail.allValues as { mode: string; autoReset: boolean };
      currentMode = v.mode as 'grid' | 'row' | 'cell';
      currentAutoReset = v.autoReset;
      if (hintEl) hintEl.innerHTML = hints[currentMode] ?? '';
    }) as EventListener);

    // Row click → row loading
    grid.on('row-click', ({ row }) => {
      if (currentMode !== 'row') return;
      const timeout = currentAutoReset ? 1000 : null;
      if (timeout) {
        grid.setRowLoading(row.id, true);
        setTimeout(() => grid.setRowLoading(row.id, false), timeout);
      } else {
        grid.setRowLoading(row.id, !grid.isRowLoading(row.id));
      }
    });

    // Cell click → cell loading
    grid.on('cell-click', ({ row, column }) => {
      if (currentMode !== 'cell') return;
      const timeout = currentAutoReset ? 1000 : null;
      if (timeout) {
        grid.setCellLoading(row.id, column.field, true);
        setTimeout(() => grid.setCellLoading(row.id, column.field, false), timeout);
      } else {
        grid.setCellLoading(row.id, column.field, !grid.isCellLoading(row.id, column.field));
      }
    });

    // Simulate button
    container.querySelector('[data-loading="simulate"]')?.addEventListener('click', async () => {
      grid.clearAllLoading();
      const timeout = currentAutoReset ? 1000 : null;

      if (currentMode === 'grid') {
        grid.loading = true;
        if (timeout) setTimeout(() => { grid.loading = false; }, timeout);
      } else if (currentMode === 'row') {
        for (const emp of employees) {
          grid.setRowLoading(emp.id, true);
          await new Promise((r) => setTimeout(r, 100));
        }
        if (timeout) setTimeout(() => grid.clearAllLoading(), timeout);
      } else if (currentMode === 'cell') {
        for (const emp of employees) {
          grid.setCellLoading(emp.id, 'email', true);
          await new Promise((r) => setTimeout(r, 100));
        }
        if (timeout) setTimeout(() => grid.clearAllLoading(), timeout);
      }
    });
  }
```

### Custom Loading Renderer

Replace the default spinner with a custom element using `loadingRenderer`:

#### Angular

```typescript
import { Component, input } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { GridConfig } from '@toolbox-web/grid-angular';

// Loading spinner component (receives `size` input)
@Component({
  selector: 'app-spinner',
  template: `
    <div class="my-spinner"
      [style.width]="size() === 'large' ? '48px' : '16px'"
      [style.height]="size() === 'large' ? '48px' : '16px'">
    </div>
  `,
})
export class SpinnerComponent {
  size = input<'large' | 'small'>('large');
}

@Component({
  imports: [Grid],
  template: `<tbw-grid [rows]="rows" [gridConfig]="config" />`,
})
export class MyGridComponent {
  config: GridConfig = {
    loadingRenderer: SpinnerComponent,
  };
}
```

The `LoadingContext` provides a `size` property: `'large'` for the grid-wide overlay (up to 48×48 px) and `'small'` for row/cell indicators (sized to the row height).

```ts
// CustomLoadingRendererDemo.astro
  import { queryGrid } from '@toolbox-web/grid';

  const grid = await queryGrid('#demo-custom-loading-renderer', true);
  const toggleBtn = document.querySelector<HTMLButtonElement>('[data-toggle="loading"]');

  if (grid) {
    grid.columns = [
      { field: 'id', header: 'ID', width: 80 },
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
      { field: 'department', header: 'Department' },
    ];

    grid.rows = [
      { id: 1, name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering' },
      { id: 2, name: 'Bob Smith', email: 'bob@example.com', department: 'Marketing' },
      { id: 3, name: 'Carol Davis', email: 'carol@example.com', department: 'Engineering' },
      { id: 4, name: 'Dan Wilson', email: 'dan@example.com', department: 'Sales' },
      { id: 5, name: 'Eve Brown', email: 'eve@example.com', department: 'HR' },
    ];

    grid.registerStyles('custom-loading', `
      .progress-bar-container {
        position: absolute;
        top: 0;
        left: 0;
        right: 0;
        height: 4px;
        background: light-dark(rgba(0,0,0,0.08), rgba(255,255,255,0.08));
        overflow: hidden;
        z-index: 1000;
      }
      .progress-bar {
        height: 100%;
        background: light-dark(#1976d2, #64b5f6);
        width: 30%;
        animation: progress-indeterminate 2s cubic-bezier(0.4,0,0.2,1) infinite;
        transform-origin: left;
      }
      @keyframes progress-indeterminate {
        0% { transform: translateX(-100%); }
        100% { transform: translateX(400%); }
      }
    `);

    grid.gridConfig = {
      getRowId: (row: { id: number }) => row.id,
      loadingRenderer: () => {
        const container = document.createElement('div');
        container.className = 'progress-bar-container';
        const bar = document.createElement('div');
        bar.className = 'progress-bar';
        container.appendChild(bar);
        return container;
      },
    };

    toggleBtn?.addEventListener('click', () => {
      grid.loading = !grid.loading;
    });
  }
```

### Empty State

When the grid has no rows and is **not** loading, it shows a built-in message (`No data to display`, or `No matching rows` when a filter plugin hides every source row). Override the message with `emptyRenderer` — typically to surface error text from a failed fetch, or to provide an actionable empty state.

```typescript
grid.gridConfig = {
  emptyRenderer: (ctx) => {
    if (loadError) return `Failed to load deals: ${loadError.message}`;
    if (ctx.filteredOut) return 'No deals match the current filter.';
    return 'No deals to display.';
  },
};
```

The renderer receives an [`EmptyContext`](/grid/api/core/interfaces/emptycontext.md) with:

- `sourceRowCount` — the number of input rows before any plugin filtering.
- `filteredOut` — `true` when `sourceRowCount > 0` but all rows were hidden (e.g. by the [FilteringPlugin](/grid/plugins/filtering.md) or grouping).

Return an `HTMLElement` for rich content (icons, buttons, multi-line layouts) or a `string` for plain text. Set `emptyRenderer: null` to suppress the overlay entirely.

The overlay mounts inside the rows container by default. Set `emptyOverlay: 'grid'` to cover the entire grid (including the header) instead — useful for full-page error states.

```typescript
grid.gridConfig = {
  emptyOverlay: 'grid',
  emptyRenderer: (ctx) => /* ... */,
};
```

:::note
The loading overlay always wins: while `grid.loading === true` the empty overlay is hidden, even if there are zero rows. This avoids flashing an empty message during the initial fetch.
:::

```ts
// EmptyStateDemo.astro
  import type { EmptyContext } from '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  type Row = { id: number; name: string; email: string; department: string };

  const allRows: Array<Row> = [
    { id: 1, name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering' },
    { id: 2, name: 'Bob Smith', email: 'bob@example.com', department: 'Marketing' },
    { id: 3, name: 'Carol Davis', email: 'carol@example.com', department: 'Engineering' },
    { id: 4, name: 'Dan Wilson', email: 'dan@example.com', department: 'Sales' },
    { id: 5, name: 'Eve Brown', email: 'eve@example.com', department: 'HR' },
  ];

  const grid = await queryGrid('#demo-empty-state', true);
  const statusEl = document.querySelector<HTMLSpanElement>('[data-status]');

  if (grid) {
    grid.columns = [
      { field: 'id', header: 'ID', width: 80 },
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
      { field: 'department', header: 'Department' },
    ];

    let errorMessage: string | null = null;

    const setStatus = (msg: string) => {
      if (statusEl) statusEl.textContent = msg;
    };

    const emptyRenderer = (ctx: EmptyContext) => {
      if (errorMessage) {
        const wrapper = document.createElement('div');
        wrapper.className = 'empty-error';
        const icon = document.createElement('div');
        icon.className = 'empty-error-icon';
        icon.textContent = '⚠';
        const title = document.createElement('div');
        title.className = 'empty-error-title';
        title.textContent = 'Failed to load data';
        const detail = document.createElement('div');
        detail.className = 'empty-error-detail';
        detail.textContent = errorMessage;
        wrapper.append(icon, title, detail);
        return wrapper;
      }
      if (ctx.filteredOut) {
        return 'No employees match the current filter.';
      }
      return 'No employees to display. Click "Load data" to fetch.';
    };

    grid.registerStyles('empty-state-demo', `
      .empty-error {
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 6px;
        text-align: center;
        max-width: 320px;
      }
      .empty-error-icon {
        font-size: 28px;
        color: light-dark(#c62828, #ef9a9a);
      }
      .empty-error-title {
        font-weight: 600;
        color: light-dark(#c62828, #ef9a9a);
      }
      .empty-error-detail {
        font-size: 0.85em;
        color: light-dark(rgba(0,0,0,0.6), rgba(255,255,255,0.6));
      }
    `);

    grid.gridConfig = {
      getRowId: (row: Row) => row.id,
      emptyRenderer,
    };

    grid.rows = [];
    setStatus('Empty state — showing default message.');

    document.querySelector('[data-action="load"]')?.addEventListener('click', () => {
      errorMessage = null;
      grid.rows = allRows;
      setStatus(`Loaded ${allRows.length} rows.`);
    });

    document.querySelector('[data-action="clear"]')?.addEventListener('click', () => {
      errorMessage = null;
      grid.rows = [];
      setStatus('Cleared — showing empty message.');
    });

    document.querySelector('[data-action="error"]')?.addEventListener('click', () => {
      errorMessage = 'Network request timed out after 30s';
      grid.rows = [];
      setStatus('Simulated error — showing custom error renderer.');
    });
  }
```

---

## Variable Row Heights

By default all rows share a fixed height (`--tbw-row-height`, default 28 px). You can configure per-row heights using a function.

### Configuration

```typescript
// Fixed height for all rows
grid.gridConfig = { rowHeight: 56 };

// Per-row height function
grid.gridConfig = {
  rowHeight: (row, index) => (row.hasDetails ? 80 : 40),
};
```

If your function returns `undefined` for a row, the grid **auto-measures** that row's actual DOM height after rendering.

### How Auto-Measurement Works

1. The grid renders rows with an estimated height.
2. After paint, it reads `offsetHeight` for each rendered row.
3. Measured heights are cached and the position cache is rebuilt.
4. A `ResizeObserver` watches for late layout shifts (font loading, lazy images) and re-measures automatically.

### Row Identity for Height Caching

Measured heights are cached using:

- **`getRowId`** / `rowId` — preferred, survives sort/filter changes
- **Object reference** (WeakMap) — fallback when no ID is configured

Provide `getRowId` for best results when rows are re-sorted, filtered, or grouped.

### Plugin-Provided Heights

Plugins can override row heights by implementing the `getRowHeight(row, index)` hook. The **MasterDetailPlugin** and **ResponsivePlugin** use this to provide expanded-row heights.

### Performance Considerations

- **Fixed heights** are fastest — the grid can calculate positions with pure math.
- **Function-based heights** add a per-row function call during position-cache rebuilds.
- **Auto-measured heights** require a DOM read pass after rendering — avoid for 10 k+ row grids unless combined with `getRowId` caching.
- When mixing fixed and auto-measured rows, return a number for most rows and `undefined` only for rows that need measurement.

```ts
// VariableRowHeightDemo.astro
import '@toolbox-web/grid';
import { queryGrid, type CellRenderContext } from '@toolbox-web/grid';

  interface Employee {
    id: number;
    name: string;
    role: string;
    department: string;
    notes: string;
  }

  const container = document.getElementById('variable-row-height-demo');
  const grid = queryGrid<Employee>('tbw-grid', container!);
  if (!grid) throw new Error('Grid not found');

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', width: 60 },
      { field: 'name', header: 'Name', width: 140 },
      { field: 'role', header: 'Role', width: 100 },
      { field: 'department', header: 'Department', width: 120 },
      { field: 'notes', header: 'Notes', renderer: (ctx: CellRenderContext<Employee>) => {
        const { row } = ctx;
        // For demonstration, render notes with a tooltip for tall rows
        const cell = document.createElement('div');
        cell.textContent = row.notes;
        if (tallRowIds.has(row.id)) {
          cell.title = 'This row has extended notes';
          cell.style.whiteSpace = 'pre-wrap';
          cell.style.fontStyle = 'italic';
        }
        return cell;
      } },
    ],
    getRowId: (row) => String(row.id),
    rowHeight: (row) => {
      // Rows with ids in tallRowIds get a taller height
      if (tallRowIds.has(row.id)) return 56;
      return undefined; // use default height
    },
  };

  // Generate 150 rows — a handful have long notes that warrant taller rows
  const tallRowIds = new Set([5, 18, 42, 77, 130]);
  const departments = ['Engineering', 'Marketing', 'Sales', 'Support', 'Finance', 'HR', 'Legal', 'Design'];
  const roles = ['Manager', 'Senior', 'Junior', 'Lead', 'Intern', 'Director', 'VP', 'Analyst'];

  grid.rows = Array.from({ length: 150 }, (_, i) => {
    const id = i + 1;
    const isTall = tallRowIds.has(id);
    return {
      id,
      name: `Employee ${id}`,
      role: roles[i % roles.length],
      department: departments[i % departments.length],
      notes: isTall
        ? `This employee has extended notes that require a taller row. ` +
          `Additional context: performance review pending, cross-team ` +
          `collaboration active, mentoring two junior engineers.`
        : `Standard note for employee ${id}.`,
    };
  });
```

---

## Events

The grid dispatches standard `CustomEvent`s for user interactions — clicks, sort changes, column resizes, and more. Plugin-specific events (selection, editing, filtering, etc.) are also available when those plugins are active.

For the complete event reference — including listening patterns per framework, cancelable events, and all plugin events — see the **[Events section](/grid/api-reference.md#events)** of the API Reference.

---

## Methods

The `<tbw-grid>` element exposes public methods for programmatic control — data manipulation, focus management, column state persistence, custom styles, shell control, loading indicators, row animation, and more. Use `createGrid()` or `queryGrid()` for type-safe access.

For the complete method reference — including signatures, return types, and factory functions — see the **[API Reference](/grid/api-reference.md#methods)** page.

---

## See Also

- [Getting Started](/grid/getting-started.md) — Installation and setup
- [Common Patterns](/grid/guides/common-patterns.md) — Full application recipes
- [Plugins](/grid/plugins.md) — Extend with selection, filtering, editing, and more
- [Theming](/grid/guides/theming.md) — CSS custom properties, dark mode, themes
- [Architecture](/grid/architecture.md) — Render scheduler, Light DOM, design decisions
- [Plugin System](/grid/plugin-development/custom-plugins.md) — Build your own plugins

---

# Demos

> Full-featured demo applications showcasing @toolbox-web/grid with 15+ plugins, custom editors, master-detail, and more.

## Reference Implementation — Employee Management (advanced, end-to-end)

This is the canonical advanced grid in this project: ~15 columns mixing text,
number, date, select and boolean; custom renderers and editors; master-detail;
multi-sort; per-column filtering; row grouping; CSV/Excel export; clipboard;
context menu; undo/redo; pinned rows; and side tool panels. In the cross-framework
`llms-full.txt` (and this page's `.md`) the source below is the
**vanilla, framework-agnostic implementation** — the `GridConfig` object is
portable verbatim to the React, Angular and Vue adapters (per RULE 0 in the
[Introduction](/grid/introduction.md): one `gridConfig` over fragmented props). In a
per-framework `llms-full-{react,vue,angular}.txt` corpus the same reference is
shown as that framework's **native implementation** (adapter components plus
JSX / SFC / component renderers and editors), drawn from
`demos/{angular,react,vue}/src/demos/employee-management/`. Only the row type and
seed data (`demos/shared/employee-management/`) are shared across all of them.

Read the files in this order: the domain model, then the grid config (columns +
`features` + manual `plugins`), then the custom renderers, editors and tool
panels, then the factory or component that wires them together.

```ts
// demos/shared/employee-management/types.ts
/**
 * Shared Data Models for Employee Management Demo
 *
 * These type definitions are shared across all framework implementations
 * (Vanilla, React, Angular, Vue) of the Employee Management demo.
 */

// Re-export grid element type for easier imports in demos
export type { TbwGrid as GridElement } from '@toolbox-web/grid';

/**
 * Represents a project that an employee is working on or has completed.
 */
export interface Project {
  id: string;
  name: string;
  role: string;
  hoursLogged: number;
  status: 'active' | 'completed' | 'on-hold';
}

/**
 * Represents a quarterly performance review for an employee.
 */
export interface PerformanceReview {
  year: number;
  quarter: string;
  score: number;
  notes: string;
}

/**
 * Represents an employee record in the HR management system.
 */
export interface Employee {
  id: number;
  firstName: string;
  lastName: string;
  email: string;
  department: string;
  team: string;
  title: string;
  level: 'Junior' | 'Mid' | 'Senior' | 'Lead' | 'Principal' | 'Director';
  salary: number;
  bonus: number;
  status: 'Active' | 'On Leave' | 'Remote' | 'Contract' | 'Terminated';
  hireDate: string;
  lastPromotion: string | null;
  manager: string | null;
  location: string;
  timezone: string;
  skills: string[];
  rating: number;
  completedProjects: number;
  activeProjects: Project[];
  performanceReviews: PerformanceReview[];
  isTopPerformer: boolean;
}

/**
 * Configuration options for the demo (used by story controls).
 */
export interface DemoConfig {
  rowCount: number;
  enableSelection: boolean;
  enableFiltering: boolean;
  enableSorting: boolean;
  enableEditing: boolean;
  enableMasterDetail: boolean;
  enableRowGrouping: boolean;
}
```

```ts
// demos/angular/src/demos/employee-management/grid-config.ts
/**
 * Grid Configuration for the Employee Management Demo
 *
 * Features are configured declaratively via `gridConfig.features` here.
 * Custom rendering/editing for individual cells uses Angular component classes
 * (e.g. `RatingDisplayComponent`, `StarRatingEditorComponent`) attached to
 * specific column definitions.
 *
 * The Angular template only retains directive bindings that own event
 * outputs the demo subscribes to (e.g. `(filterChange)` via
 * `GridFilteringDirective`).
 */
// ═════════════════════════════════════════════════════════════════════════════
// FEATURE IMPORTS — register the features used in `gridConfig.features` below.
// Each side-effect import calls `registerFeature(name, factory)` so the grid
// can look the factory up by string key when it walks `features`.
// Tree-shakeable: only imported features ship in the bundle.
//
// `editing`, `filtering`, `master-detail`, and `responsive` are imported in
// `employee-management.component.ts` instead because they are also referenced
// from the component's `imports` array (event-bearing directives) or its
// template (`<tbw-grid-detail>`, `<tbw-grid-responsive-card>`).
// ═════════════════════════════════════════════════════════════════════════════
import '@toolbox-web/grid-angular/features/clipboard';
import '@toolbox-web/grid-angular/features/column-virtualization';
import '@toolbox-web/grid-angular/features/context-menu';
import '@toolbox-web/grid-angular/features/export';
import '@toolbox-web/grid-angular/features/grouping-columns';
import '@toolbox-web/grid-angular/features/multi-sort';
import '@toolbox-web/grid-angular/features/pinned-columns';
import '@toolbox-web/grid-angular/features/pinned-rows';
import '@toolbox-web/grid-angular/features/reorder-columns';
import '@toolbox-web/grid-angular/features/selection';
import '@toolbox-web/grid-angular/features/undo-redo';
import '@toolbox-web/grid-angular/features/visibility';

import { DEPARTMENTS, type Employee } from '@demo/shared/employee-management';
import type { GridConfig } from '@toolbox-web/grid-angular';
import { filteredCountPanel, rowCountPanel } from '@toolbox-web/grid/plugins/pinned-rows';
import { StarRatingEditorComponent } from './editors/star-rating-editor.component';
import { RatingDisplayComponent } from './renderers/rating-display.component';

export interface GridConfigOptions {
  enableSelection: boolean;
  enableFiltering: boolean;
  enableSorting: boolean;
  enableEditing: boolean;
  enableMasterDetail: boolean;
}

/**
 * Column groups for the employee grid.
 * Used in the gridConfig.columnGroups configuration.
 */
export const COLUMN_GROUPS = [
  { id: 'employee', header: 'Employee Info', children: ['firstName', 'lastName', 'email'] },
  {
    id: 'organization',
    header: 'Organization',
    children: ['department', 'team', 'title', 'level'],
  },
  { id: 'compensation', header: 'Compensation', children: ['salary', 'bonus'] },
  {
    id: 'status',
    header: 'Status & Performance',
    children: ['status', 'hireDate', 'rating', 'isTopPerformer', 'location'],
  },
];

export function createGridConfig(options: GridConfigOptions): GridConfig<Employee> {
  const { enableSelection, enableFiltering, enableSorting, enableEditing, enableMasterDetail } =
    options;

  return {
    // Column groups (augmented by GroupingColumnsPlugin)
    columnGroups: COLUMN_GROUPS,
    // Column definitions - templates come from light DOM via Angular adapter
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 70, sortable: true },
      {
        field: 'firstName',
        header: 'First Name',
        minWidth: 100,
        editable: enableEditing,
        sortable: true,
        resizable: true,
      },
      {
        field: 'lastName',
        header: 'Last Name',
        minWidth: 100,
        editable: enableEditing,
        sortable: true,
        resizable: true,
      },
      { field: 'email', header: 'Email', minWidth: 200, resizable: true },
      {
        field: 'department',
        header: 'Dept',
        width: 120,
        sortable: true,
        editable: enableEditing,
        type: 'select',
        options: DEPARTMENTS.map((d) => ({ label: d, value: d })),
      },
      { field: 'team', header: 'Team', width: 110, sortable: true },
      { field: 'title', header: 'Title', minWidth: 160, editable: enableEditing, resizable: true },
      {
        field: 'level',
        header: 'Level',
        width: 90,
        sortable: true,
        editable: enableEditing,
        type: 'select',
        options: ['Junior', 'Mid', 'Senior', 'Lead', 'Principal', 'Director'].map((l) => ({
          label: l,
          value: l,
        })),
      },
      {
        field: 'salary',
        header: 'Salary',
        type: 'number',
        width: 110,
        editable: enableEditing,
        sortable: true,
        resizable: true,
        format: (v: number) =>
          v.toLocaleString('en-US', {
            style: 'currency',
            currency: 'USD',
            maximumFractionDigits: 0,
          }),
      },
      {
        field: 'bonus',
        header: 'Bonus',
        type: 'number',
        width: 180,
        sortable: true,
        editable: enableEditing,
        // editor comes from light DOM template
        format: (v: number) =>
          v.toLocaleString('en-US', {
            style: 'currency',
            currency: 'USD',
            maximumFractionDigits: 0,
          }),
      },
      {
        field: 'status',
        header: 'Status',
        width: 140,
        sortable: true,
        editable: enableEditing,
        // editor and viewRenderer come from light DOM templates
      },
      {
        field: 'hireDate',
        header: 'Hire Date',
        type: 'date',
        width: 130,
        sortable: true,
        editable: enableEditing,
        // editor comes from light DOM template
      },
      {
        field: 'rating',
        header: 'Rating',
        type: 'number',
        width: 120,
        sortable: true,
        editable: enableEditing,
        // Component-class based renderer and editor (no template needed!)
        renderer: RatingDisplayComponent,
        editor: StarRatingEditorComponent,
      },
      { field: 'isTopPerformer', header: '⭐', type: 'boolean', width: 50, sortable: false },
      { field: 'location', header: 'Location', width: 110, sortable: true },
    ],
    // Shell configuration
    shell: {
      toolPanel: { position: 'right', width: 300 },
    },

    // Grid-wide feature toggles (used by plugins that support enable/disable)
    sortable: enableSorting,
    filterable: enableFiltering,
    selectable: enableSelection,

    // Declarative feature configuration. The Angular template no longer
    // carries `[clipboard]` / `[contextMenu]` / `[reorderColumns]` / etc.
    // bindings — those features are configured here. Directives that own
    // event outputs the demo subscribes to (e.g. `GridFilteringDirective`
    // → `(filterChange)`) remain in the component's `imports`, but their
    // input is empty and feature config flows through here.
    features: {
      selection: enableSelection ? 'range' : undefined,
      multiSort: enableSorting ? 'multi' : undefined,
      filtering: enableFiltering ? { debounceMs: 200 } : undefined,
      editing: enableEditing ? 'dblclick' : undefined,
      undoRedo: enableEditing ? { maxHistorySize: 100 } : undefined,
      clipboard: true,
      contextMenu: true,
      reorderColumns: true,
      visibility: true,
      pinnedColumns: true,
      columnVirtualization: true,
      export: true,
      groupingColumns: { lockGroupOrder: true },
      responsive: {
        breakpoint: 700,
        cardRowHeight: 80,
        hiddenColumns: [
          'id',
          'email',
          'team',
          'level',
          'bonus',
          'hireDate',
          'isTopPerformer',
          'location',
        ],
      },
      masterDetail: enableMasterDetail
        ? { showExpandColumn: true, animation: 'slide' as const }
        : undefined,
      pinnedRows: {
        slots: [
          {
            id: 'totals',
            position: 'bottom',
            label: 'Summary:',
            cells: {
              salary: (rows: unknown[]) =>
                (rows as Employee[])
                  .reduce((acc, r) => acc + (r.salary || 0), 0)
                  .toLocaleString('en-US', {
                    style: 'currency',
                    currency: 'USD',
                    maximumFractionDigits: 0,
                  }),
              bonus: (rows: unknown[]) =>
                (rows as Employee[])
                  .reduce((acc, r) => acc + (r.bonus || 0), 0)
                  .toLocaleString('en-US', {
                    style: 'currency',
                    currency: 'USD',
                    maximumFractionDigits: 0,
                  }),
              rating: (rows: unknown[]) => {
                const vals = (rows as Employee[]).map((r) => r.rating).filter(Boolean);
                return vals.length
                  ? `Avg: ${(vals.reduce((a, b) => a + b, 0) / vals.length).toFixed(2)}`
                  : '';
              },
            },
          },
          { id: 'count', position: 'bottom', render: rowCountPanel() },
          { id: 'filtered', position: 'bottom', render: filteredCountPanel() },
        ],
      },
    },
  };
}
```

```ts
// demos/angular/src/demos/employee-management/employee-management.component.ts
// Feature imports for the directives wired in this component's `imports` array
// (events the demo subscribes to). All other feature side-effect imports live
// next to the matching `gridConfig.features` keys in `./grid-config.ts`.
import '@toolbox-web/grid-angular/features/editing';
import '@toolbox-web/grid-angular/features/filtering';
// Master-detail and responsive must be side-effect-imported in the component
// so their `<tbw-grid-detail>` / `<tbw-grid-responsive-card>` template elements
// get wired into the corresponding plugin's renderer in ngAfterContentInit.
import '@toolbox-web/grid-angular/features/master-detail';
import '@toolbox-web/grid-angular/features/responsive';

import { CurrencyPipe } from '@angular/common';
import { Component, computed, inject, signal } from '@angular/core';
import {
  FormBuilder,
  FormGroup,
  FormsModule,
  ReactiveFormsModule,
  Validators,
} from '@angular/forms';
import { generateEmployees, type Employee } from '@demo/shared/employee-management';
import { shadowDomStyles } from '@demo/shared/employee-management/styles';
import {
  CellCommitEvent,
  Grid,
  GridResponsiveCard,
  GridToolPanel,
  injectGrid,
  TbwGridColumn,
  TbwGridHeader,
  TbwGridToolButtons,
  TbwRenderer,
} from '@toolbox-web/grid-angular';
import {
  GridEditingDirective,
  GridLazyForm,
  TbwEditor,
} from '@toolbox-web/grid-angular/features/editing';
import { injectGridExport } from '@toolbox-web/grid-angular/features/export';
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import { GridDetailView } from '@toolbox-web/grid-angular/features/master-detail';
import { createGridConfig } from './grid-config';

// Import components so they're available in templates
// Note: RatingDisplayComponent and StarRatingEditorComponent are configured via gridConfig,
// not imported here (they use component-class column config instead of templates)
import { BonusSliderEditorComponent } from './editors/bonus-slider-editor.component';
import { DateEditorComponent } from './editors/date-editor.component';
import { StatusSelectEditorComponent } from './editors/status-select-editor.component';
import { DetailPanelComponent } from './renderers/detail-panel.component';
import { StatusBadgeComponent } from './renderers/status-badge.component';
import { TopPerformerComponent } from './renderers/top-performer.component';
import { AnalyticsPanelComponent, QuickFiltersPanelComponent } from './tool-panels';

@Component({
  selector: 'app-employee-management',
  imports: [
    CurrencyPipe,
    FormsModule,
    ReactiveFormsModule,
    Grid,
    GridDetailView,
    GridFilteringDirective,
    GridEditingDirective,
    GridLazyForm,
    GridResponsiveCard,
    GridToolPanel,
    TbwGridColumn,
    TbwGridHeader,
    TbwGridToolButtons,
    TbwRenderer,
    TbwEditor,
    // Renderer components (RatingDisplayComponent is configured in gridConfig instead)
    StatusBadgeComponent,
    TopPerformerComponent,
    DetailPanelComponent,
    // Editor components (StarRatingEditorComponent is configured in gridConfig instead)
    StatusSelectEditorComponent,
    BonusSliderEditorComponent,
    DateEditorComponent,
    // Tool panel components
    QuickFiltersPanelComponent,
    AnalyticsPanelComponent,
  ],
  templateUrl: './employee-management.component.html',
})
export class EmployeeManagementComponent {
  private fb = inject(FormBuilder);

  rowCount = signal(200);
  enableSelection = signal(true);
  enableFiltering = signal(true);
  enableSorting = signal(true);
  enableEditing = signal(true);
  enableMasterDetail = signal(true);

  // Custom styles for shadow DOM (editors, renderers, detail panels)
  // The Grid directive automatically injects these into the grid's shadow DOM
  customStyles = shadowDomStyles;

  // Generate employee data - recomputed when rowCount changes
  rows = computed(() => generateEmployees(this.rowCount()));

  /**
   * Lazy form factory - creates a FormGroup only when a row enters edit mode.
   * This is ~20-100x more efficient than creating FormGroups for all rows upfront!
   *
   * For 200 rows with 22 fields, the old approach created 4,400 FormControls.
   * This approach creates ~10 FormControls (only for the row being edited).
   */
  createRowForm = (employee: Employee): FormGroup =>
    this.fb.group({
      // Only include EDITABLE fields - no need for disabled read-only fields
      firstName: [employee.firstName, Validators.required],
      lastName: [employee.lastName, Validators.required],
      department: [employee.department],
      title: [employee.title],
      level: [employee.level, [Validators.min(1), Validators.max(10)]],
      salary: [employee.salary, [Validators.required, Validators.min(0)]],
      bonus: [employee.bonus, [Validators.min(0), Validators.max(100)]],
      status: [employee.status],
      hireDate: [employee.hireDate],
      rating: [employee.rating, [Validators.min(0), Validators.max(5)]],
    });

  // Grid config - recomputed when feature flags change
  gridConfig = computed(() =>
    createGridConfig({
      enableSelection: this.enableSelection(),
      enableFiltering: this.enableFiltering(),
      enableSorting: this.enableSorting(),
      enableEditing: this.enableEditing(),
      enableMasterDetail: this.enableMasterDetail(),
    }),
  );

  // Typed grid access via injectGrid - cleaner than viewChild!
  grid = injectGrid<Employee>();

  // Feature-scoped hook for export functionality
  gridExport = injectGridExport();

  exportCsv(): void {
    this.gridExport.exportToCsv('employees.csv');
  }

  exportExcel(): void {
    this.gridExport.exportToExcel('employees.xlsx');
  }

  /**
   * Handle cell commit events at the grid level.
   * This demonstrates the event bubbling feature - instead of handling
   * commit in each editor template, we can handle it centrally here.
   */
  onCellCommit(event: CellCommitEvent): void {
    console.log(`[Grid] Cell committed: ${event.field} = ${event.value} (row ${event.rowIndex})`);
    // Example: could trigger auto-save, show notification, etc.
  }

  /**
   * Filter-change handler wired via `(filterChange)` on <tbw-grid>. Owned by
   * `GridFilteringDirective` from `@toolbox-web/grid-angular/features/filtering`,
   * which is added to this component's `imports` above. Without that import
   * Angular's compiler would error with `Can't bind to 'filterChange'...`.
   */
  onFilterChange(event: unknown): void {
    console.log('[Grid] filter-change', event);
  }

  /**
   * Get department color for responsive card avatar.
   */
  getDepartmentColor(department: string): string {
    const colors: Record<string, string> = {
      Engineering: '#3b82f6',
      Marketing: '#ec4899',
      Sales: '#f59e0b',
      HR: '#10b981',
      Finance: '#6366f1',
      Legal: '#8b5cf6',
      Operations: '#14b8a6',
      'Customer Support': '#f97316',
    };
    return colors[department] ?? '#6b7280';
  }
}
```

```html
// demos/angular/src/demos/employee-management/employee-management.component.html
<div class="demo-container">
  <header class="demo-header">
    <div class="demo-controls">
      <label>
        <span class="row-count-display">
          Rows: <strong>{{ rowCount() }}</strong>
        </span>
        <input type="range" [(ngModel)]="rowCount" min="50" max="1000" step="50" />
      </label>
      <label>
        <input type="checkbox" [(ngModel)]="enableSelection" />
        Selection
      </label>
      <label>
        <input type="checkbox" [(ngModel)]="enableFiltering" />
        Filtering
      </label>
      <label>
        <input type="checkbox" [(ngModel)]="enableSorting" />
        Sorting
      </label>
      <label>
        <input type="checkbox" [(ngModel)]="enableEditing" />
        Editing
      </label>
      <label>
        <input type="checkbox" [(ngModel)]="enableMasterDetail" />
        Master-Detail
      </label>
    </div>
  </header>

  <div class="grid-wrapper">
    <div class="demo-grid">
      <!--
        Feature configuration lives entirely in `gridConfig.features` (see
        `grid-config.ts`). Only event-bearing directives are wired here:
          - GridEditingDirective   -> (cellCommit)
          - GridFilteringDirective -> (filterChange)
        The directives still attach (their selectors match the event bindings)
        but do not own feature config.
      -->
      <tbw-grid
        #grid
        id="employee-grid"
        [rows]="rows()"
        [lazyForm]="createRowForm"
        [gridConfig]="gridConfig()"
        [customStyles]="customStyles"
        (cellCommit)="onCellCommit($event)"
        (filterChange)="onFilterChange($event)"
      >
        <!-- Shell configuration with title -->
        <tbw-grid-header title="Employee Management System (Angular)"></tbw-grid-header>

        <!-- Toolbar buttons container -->
        <tbw-grid-tool-buttons>
          <button
            class="tbw-toolbar-btn"
            title="Export CSV"
            aria-label="Export CSV"
            (click)="exportCsv()"
          >
            📄
          </button>
          <button
            class="tbw-toolbar-btn"
            title="Export Excel"
            aria-label="Export Excel"
            (click)="exportExcel()"
          >
            📊
          </button>
        </tbw-grid-tool-buttons>

        <!-- Column templates - column definitions come from gridConfig, these add Angular templates -->
        <!-- Using structural directives for cleaner syntax -->
        <!-- Auto-wiring: editor components just emit (commit) and (cancel) events, no explicit binding needed -->
        <!-- The 'control' variable provides access to the FormControl from the FormArray binding -->
        <!-- When control is provided, the editor derives value from control.value automatically -->
        <tbw-grid-column field="status">
          <app-status-badge *tbwRenderer="let value" [value]="value" />
          @if (enableEditing()) {
            <app-status-select-editor *tbwEditor="let _; control as control" [control]="control" />
          }
        </tbw-grid-column>
        <tbw-grid-column field="bonus">
          @if (enableEditing()) {
            <app-bonus-slider-editor
              *tbwEditor="let value; row as row"
              [value]="value"
              [salary]="row.salary"
            />
          }
        </tbw-grid-column>
        <!-- Rating column uses component-class config in gridConfig instead of templates -->
        <!-- See grid-config.ts: { field: 'rating', renderer: RatingDisplayComponent, editor: StarRatingEditorComponent } -->
        <tbw-grid-column field="hireDate">
          @if (enableEditing()) {
            <app-date-editor *tbwEditor="let value" [value]="value" />
          }
        </tbw-grid-column>
        <tbw-grid-column field="isTopPerformer">
          <app-top-performer *tbwRenderer="let value" [value]="value" />
        </tbw-grid-column>

        <!-- Master-detail template -->
        @if (enableMasterDetail()) {
          <tbw-grid-detail [showExpandColumn]="true" animation="slide">
            <ng-template let-row>
              <app-detail-panel [employee]="row" />
            </ng-template>
          </tbw-grid-detail>
        }

        <!-- Responsive card template for mobile/narrow layouts -->
        <tbw-grid-responsive-card>
          <ng-template let-emp let-idx="index">
            <div class="responsive-employee-card">
              <div
                class="responsive-employee-card__avatar"
                [style.background-color]="getDepartmentColor(emp.department)"
              >
                {{ emp.firstName.charAt(0) }}{{ emp.lastName.charAt(0) }}
              </div>
              <div class="responsive-employee-card__content">
                <div class="responsive-employee-card__header">
                  <span class="responsive-employee-card__name"
                    >{{ emp.firstName }} {{ emp.lastName }}</span
                  >
                  <app-status-badge [value]="emp.status" />
                </div>
                <div class="responsive-employee-card__title">{{ emp.title }}</div>
                <div class="responsive-employee-card__meta">
                  <span
                    class="responsive-employee-card__dept"
                    [style.color]="getDepartmentColor(emp.department)"
                    >{{ emp.department }}</span
                  >
                  <span class="responsive-employee-card__separator">•</span>
                  <span class="responsive-employee-card__salary">{{
                    emp.salary | currency: 'USD' : 'symbol' : '1.0-0'
                  }}</span>
                  <span class="responsive-employee-card__separator">•</span>
                  <span class="responsive-employee-card__rating"
                    >{{ emp.rating.toFixed(1) }} ★</span
                  >
                  @if (emp.isTopPerformer) {
                    <span class="responsive-employee-card__top-performer">⭐</span>
                  }
                </div>
              </div>
            </div>
          </ng-template>
        </tbw-grid-responsive-card>

        <!-- Custom Tool Panels -->
        <tbw-grid-tool-panel
          id="quick-filters"
          title="Quick Filters"
          icon="🔍"
          tooltip="Apply quick filters to the data"
          [order]="10"
        >
          <ng-template let-grid>
            <app-quick-filters-panel [grid]="grid" />
          </ng-template>
        </tbw-grid-tool-panel>

        <tbw-grid-tool-panel
          id="analytics"
          title="Analytics"
          icon="📈"
          tooltip="View data analytics and insights"
          [order]="20"
        >
          <ng-template let-grid>
            <app-analytics-panel [grid]="grid" [rows]="rows()" />
          </ng-template>
        </tbw-grid-tool-panel>
      </tbw-grid>
    </div>
  </div>
</div>
```

```ts
// demos/angular/src/demos/employee-management/renderers/status-badge.component.ts
import { Component, input } from '@angular/core';
import type { Employee } from '@demo/shared/employee-management';
import type { ColumnConfig } from '@toolbox-web/grid';
import type { CellRenderer } from '@toolbox-web/grid-angular';

/**
 * Status badge renderer component implementing CellRenderer interface.
 * Can be used via both template syntax (*tbwRenderer) and component-class column config.
 */
@Component({
  selector: 'app-status-badge',
  template: `<span class="status-badge" [class]="badgeClass()">{{ value() }}</span>`,
  styles: [
    `
      :host {
        display: contents;
      }
    `,
  ],
})
export class StatusBadgeComponent implements CellRenderer<Employee, string> {
  // CellRenderer interface inputs
  value = input<string>('');
  row = input<Employee>();
  column = input<ColumnConfig<Employee>>();

  badgeClass = () => {
    const v = this.value();
    return v ? `status-badge--${v.toLowerCase().replace(/\s+/g, '-')}` : '';
  };
}
```

```ts
// demos/angular/src/demos/employee-management/renderers/top-performer.component.ts
import { Component, input } from '@angular/core';

@Component({
  selector: 'app-top-performer',
  template: `
    <span
      class="top-performer-star"
      [class.top-performer-star--active]="value()"
      [class.top-performer-star--inactive]="!value()"
    >
      {{ value() ? '★' : '☆' }}
    </span>
  `,
  styles: [],
})
export class TopPerformerComponent {
  value = input<boolean>(false);
}
```

```ts
// demos/angular/src/demos/employee-management/renderers/rating-display.component.ts
import { Component, computed, input } from '@angular/core';
import type { Employee } from '@demo/shared/employee-management';
import type { ColumnConfig } from '@toolbox-web/grid';
import type { CellRenderer } from '@toolbox-web/grid-angular';

/**
 * Rating display renderer implementing CellRenderer interface.
 * Can be used via template syntax (*tbwRenderer) or component-class column config.
 */
@Component({
  selector: 'app-rating-display',
  template: `<span class="rating-display" [class]="levelClass()">{{ displayValue() }} ★</span>`,
  styles: [],
})
export class RatingDisplayComponent implements CellRenderer<Employee, number> {
  // CellRenderer interface inputs
  value = input<number>(0);
  row = input<Employee>();
  column = input<ColumnConfig<Employee>>();

  displayValue = computed(() => (this.value() ?? 0).toFixed(1));

  levelClass = computed(() => {
    const v = this.value() ?? 0;
    const level = v >= 4.5 ? 'high' : v >= 3.5 ? 'medium' : 'low';
    return `rating-display--${level}`;
  });
}
```

```ts
// demos/angular/src/demos/employee-management/renderers/detail-panel.component.ts
import { Component, computed, input } from '@angular/core';
import type { Employee } from '@demo/shared/employee-management';

@Component({
  selector: 'app-detail-panel',
  template: `
    <div class="detail-panel">
      <div class="detail-grid">
        <div class="detail-section">
          <h4 class="detail-section__title">Active Projects</h4>
          <table class="detail-table">
            <thead>
              <tr class="detail-table__header">
                <th class="detail-table__header-cell">ID</th>
                <th class="detail-table__header-cell">Project</th>
                <th class="detail-table__header-cell">Role</th>
                <th class="detail-table__header-cell">Hours</th>
                <th class="detail-table__header-cell">Status</th>
              </tr>
            </thead>
            <tbody>
              @for (project of employee().activeProjects; track project.id) {
                <tr class="detail-table__row">
                  <td class="detail-table__cell">{{ project.id }}</td>
                  <td class="detail-table__cell">{{ project.name }}</td>
                  <td class="detail-table__cell">{{ project.role }}</td>
                  <td class="detail-table__cell">{{ project.hoursLogged }}h</td>
                  <td class="detail-table__cell">
                    <span class="project-status" [class]="'project-status--' + project.status">
                      {{ project.status }}
                    </span>
                  </td>
                </tr>
              }
            </tbody>
          </table>
        </div>
        <div class="detail-section">
          <h4 class="detail-section__title">Performance Reviews</h4>
          <div class="reviews-grid">
            @for (review of recentReviews(); track review.quarter + review.year) {
              <div class="review-card">
                <div class="review-card__period">{{ review.quarter }} {{ review.year }}</div>
                <div class="review-card__score" [class]="getScoreClass(review.score)">
                  {{ review.score.toFixed(1) }}
                </div>
                <div class="review-card__notes">{{ review.notes }}</div>
              </div>
            }
          </div>
          <div class="skills-container">
            <h4 class="detail-section__title">Skills</h4>
            @for (skill of employee().skills; track skill) {
              <span class="skill-tag">{{ skill }}</span>
            }
          </div>
        </div>
      </div>
    </div>
  `,
  styles: [],
})
export class DetailPanelComponent {
  employee = input.required<Employee>();

  recentReviews = computed(() => this.employee().performanceReviews.slice(-4));

  getScoreClass(score: number): string {
    const level = score >= 4 ? 'high' : score >= 3 ? 'medium' : 'low';
    return `review-card__score--${level}`;
  }
}
```

```ts
// demos/angular/src/demos/employee-management/editors/star-rating-editor.component.ts
import { CommonModule } from '@angular/common';
import { AfterViewInit, Component, effect, ElementRef, signal, viewChild } from '@angular/core';
import type { Employee } from '@demo/shared/employee-management';
import { BaseGridEditor } from '@toolbox-web/grid-angular/features/editing';

/**
 * Star rating editor extending BaseGridEditor.
 *
 * Demonstrates:
 * - Using currentValue() from base class
 * - Local signal for UI state
 * - Keyboard navigation
 */
@Component({
  selector: 'app-star-rating-editor',
  imports: [CommonModule],
  template: `
    <div class="star-rating-editor" #container tabindex="0" (keydown)="onKeyDown($event)">
      @for (star of stars; track star) {
        <span
          class="star-rating-editor__star"
          [class.star-rating-editor__star--filled]="star <= ratingValue()"
          [class.star-rating-editor__star--empty]="star > ratingValue()"
          (click)="onStarClick(star)"
        >
          {{ star <= Math.round(ratingValue()) ? '★' : '☆' }}
        </span>
      }
      <span class="star-rating-editor__label">{{ ratingValue().toFixed(1) }}</span>
    </div>
  `,
  styles: [],
})
export class StarRatingEditorComponent
  extends BaseGridEditor<Employee, number>
  implements AfterViewInit
{
  container = viewChild.required<ElementRef<HTMLDivElement>>('container');

  /** Local signal for UI state during editing */
  ratingValue = signal(3);
  readonly stars = [1, 2, 3, 4, 5];
  readonly Math = Math;

  constructor() {
    super();
    // Sync from base class currentValue (handles control vs value)
    effect(() => {
      this.ratingValue.set(this.currentValue() ?? 3);
    });
  }

  ngAfterViewInit(): void {
    setTimeout(() => this.container().nativeElement.focus(), 0);
  }

  onStarClick(star: number): void {
    this.ratingValue.set(star);
    this.commitValue(star);
  }

  onKeyDown(event: KeyboardEvent): void {
    const current = this.ratingValue();
    if (event.key === 'ArrowLeft' && current > 1) {
      this.ratingValue.set(Math.max(1, current - 0.5));
    } else if (event.key === 'ArrowRight' && current < 5) {
      this.ratingValue.set(Math.min(5, current + 0.5));
    } else if (event.key === 'Enter') {
      this.commitValue(this.ratingValue());
    } else if (event.key === 'Escape') {
      this.cancelEdit();
    }
  }
}
```

```ts
// demos/angular/src/demos/employee-management/editors/bonus-slider-editor.component.ts
import { CommonModule } from '@angular/common';
import {
  AfterViewInit,
  Component,
  computed,
  effect,
  ElementRef,
  input,
  viewChild,
} from '@angular/core';
import { FormsModule } from '@angular/forms';
import type { Employee } from '@demo/shared/employee-management';
import { BaseGridEditor } from '@toolbox-web/grid-angular/features/editing';

/**
 * Bonus slider editor extending BaseGridEditor.
 *
 * Demonstrates:
 * - Computed signals based on row() from base class
 * - Custom input (salary) in addition to inherited inputs
 * - Validation styling via isInvalid()
 */
@Component({
  selector: 'app-bonus-slider-editor',
  imports: [CommonModule, FormsModule],
  template: `
    <div class="bonus-slider-editor">
      <input
        #slider
        type="range"
        class="bonus-slider-editor__slider"
        [class.is-invalid]="isInvalid()"
        [min]="minBonus()"
        [max]="maxBonus()"
        [(ngModel)]="currentValueModel"
        (change)="onCommit()"
        (keydown)="onKeyDown($event)"
      />
      <span class="bonus-slider-editor__display">
        <strong [class]="getColorClass()">{{ formatCurrency(currentValueModel) }}</strong>
        <small class="bonus-slider-editor__percent">({{ getPercent() }}%)</small>
      </span>
    </div>
  `,
  styles: [],
})
export class BonusSliderEditorComponent
  extends BaseGridEditor<Employee, number>
  implements AfterViewInit
{
  /** Legacy input for template-based usage (explicit salary override) */
  salary = input<number>();

  slider = viewChild.required<ElementRef<HTMLInputElement>>('slider');

  currentValueModel = 0;

  /**
   * Effective salary - prefers explicit `salary` input, falls back to row().salary
   */
  effectiveSalary = computed(() => {
    const explicitSalary = this.salary();
    if (explicitSalary !== undefined) return explicitSalary;

    const rowData = this.row();
    return rowData?.salary ?? 100000;
  });

  minBonus = computed(() => Math.round(this.effectiveSalary() * 0.02));
  maxBonus = computed(() => Math.round(this.effectiveSalary() * 0.25));

  constructor() {
    super();
    effect(() => {
      // Use currentValue() from base class (handles control vs value)
      this.currentValueModel = this.currentValue() ?? Math.round(this.effectiveSalary() * 0.1);
    });
  }

  ngAfterViewInit(): void {
    setTimeout(() => this.slider().nativeElement.focus(), 0);
  }

  onCommit(): void {
    this.commitValue(this.currentValueModel);
  }

  onKeyDown(event: KeyboardEvent): void {
    if (event.key === 'Enter') {
      this.commitValue(this.currentValueModel);
    } else if (event.key === 'Escape') {
      this.cancelEdit();
    }
  }

  getPercent(): string {
    return ((this.currentValueModel / this.effectiveSalary()) * 100).toFixed(1);
  }

  getColorClass(): string {
    const percent = parseFloat(this.getPercent());
    if (percent >= 15) return 'bonus-slider-editor__value--high';
    if (percent >= 10) return 'bonus-slider-editor__value--medium';
    return 'bonus-slider-editor__value--low';
  }

  formatCurrency(value: number): string {
    return `$${value.toLocaleString()}`;
  }
}
```

```ts
// demos/angular/src/demos/employee-management/editors/status-select-editor.component.ts
import { CommonModule } from '@angular/common';
import { AfterViewInit, Component, effect, ElementRef, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import type { Employee } from '@demo/shared/employee-management';
import { BaseGridEditor } from '@toolbox-web/grid-angular/features/editing';

interface StatusConfig {
  bg: string;
  text: string;
  icon: string;
}

/**
 * Status select editor extending BaseGridEditor.
 *
 * Demonstrates how to build custom editors using the base class:
 * - Inherits value, row, column, control inputs
 * - Inherits commit, cancel outputs
 * - Uses currentValue() computed signal for value resolution
 * - Uses isInvalid(), isDirty() for validation styling
 * - Overrides getErrorMessage() for custom error messages
 */
@Component({
  selector: 'app-status-select-editor',
  imports: [CommonModule, FormsModule],
  template: `
    <div class="status-select-editor" [class.has-control]="control()">
      <select
        #selectEl
        class="status-select-editor__select"
        [class.is-invalid]="isInvalid()"
        [class.is-dirty]="isDirty()"
        [(ngModel)]="currentValueModel"
        (change)="onCommit()"
        (keydown)="onKeyDown($event)"
      >
        @for (status of statuses; track status) {
          <option [value]="status">{{ statusConfig[status].icon }} {{ status }}</option>
        }
      </select>
      @if (hasErrors()) {
        <div class="status-select-editor__error">
          {{ firstErrorMessage() }}
        </div>
      }
    </div>
  `,
  styles: [
    `
      .status-select-editor__select.is-invalid {
        border-color: #dc3545;
        box-shadow: 0 0 0 2px rgba(220, 53, 69, 0.25);
      }
      .status-select-editor__select.is-dirty {
        border-left: 3px solid #ffc107;
      }
      .status-select-editor__error {
        color: #dc3545;
        font-size: 11px;
        margin-top: 2px;
      }
    `,
  ],
})
export class StatusSelectEditorComponent
  extends BaseGridEditor<Employee, string>
  implements AfterViewInit
{
  selectEl = viewChild.required<ElementRef<HTMLSelectElement>>('selectEl');

  currentValueModel = 'Active';
  readonly statuses = ['Active', 'Remote', 'On Leave', 'Contract', 'Terminated'];
  readonly statusConfig: Record<string, StatusConfig> = {
    Active: { bg: '#d4edda', text: '#155724', icon: '✓' },
    Remote: { bg: '#cce5ff', text: '#004085', icon: '🏠' },
    'On Leave': { bg: '#fff3cd', text: '#856404', icon: '🌴' },
    Contract: { bg: '#e2e3e5', text: '#383d41', icon: '📄' },
    Terminated: { bg: '#f8d7da', text: '#721c24', icon: '✗' },
  };

  constructor() {
    super();
    // Sync currentValueModel with the resolved value (from control or input)
    effect(() => {
      const value = this.currentValue();
      this.currentValueModel = value || 'Active';
    });
  }

  /**
   * Override to provide custom error messages for status-specific validation.
   */
  protected override getErrorMessage(errorKey: string, errorValue?: unknown): string {
    if (errorKey === 'invalidStatus') return 'Invalid status value';
    return super.getErrorMessage(errorKey, errorValue);
  }

  ngAfterViewInit(): void {
    setTimeout(() => this.selectEl().nativeElement.focus(), 0);
  }

  onCommit(): void {
    this.commitValue(this.currentValueModel);
  }

  onKeyDown(event: KeyboardEvent): void {
    if (event.key === 'Escape') {
      event.preventDefault();
      this.cancelEdit();
    }
  }
}
```

```ts
// demos/angular/src/demos/employee-management/editors/date-editor.component.ts
import { CommonModule } from '@angular/common';
import { AfterViewInit, Component, effect, ElementRef, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { BaseGridEditor } from '@toolbox-web/grid-angular/features/editing';

/**
 * Date editor extending BaseGridEditor.
 *
 * Simple date picker that demonstrates minimal BaseGridEditor usage.
 */
@Component({
  selector: 'app-date-editor',
  imports: [CommonModule, FormsModule],
  template: `
    <input
      #dateInput
      type="date"
      class="date-editor"
      [class.is-invalid]="isInvalid()"
      [(ngModel)]="currentValueModel"
      (change)="onCommit()"
      (keydown)="onKeyDown($event)"
    />
  `,
  styles: [
    `
      .date-editor.is-invalid {
        border-color: #dc3545;
        box-shadow: 0 0 0 2px rgba(220, 53, 69, 0.25);
      }
    `,
  ],
})
export class DateEditorComponent extends BaseGridEditor<unknown, string> implements AfterViewInit {
  dateInput = viewChild.required<ElementRef<HTMLInputElement>>('dateInput');

  currentValueModel = '';

  constructor() {
    super();
    effect(() => {
      this.currentValueModel = this.currentValue() || '';
    });
  }

  ngAfterViewInit(): void {
    setTimeout(() => this.dateInput().nativeElement.focus(), 0);
  }

  onCommit(): void {
    this.commitValue(this.currentValueModel);
  }

  onKeyDown(event: KeyboardEvent): void {
    if (event.key === 'Enter') {
      this.commitValue(this.currentValueModel);
    } else if (event.key === 'Escape') {
      this.cancelEdit();
    }
  }
}
```

```ts
// demos/angular/src/demos/employee-management/tool-panels/quick-filters-panel.component.ts
import { Component, input, OnInit } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { DEPARTMENTS, type Employee, type GridElement } from '@demo/shared/employee-management';
import { FilteringPlugin } from '@toolbox-web/grid/all';

/**
 * Quick Filters tool panel component.
 * Provides department, level, status, and rating filters.
 */
@Component({
  selector: 'app-quick-filters-panel',
  imports: [FormsModule],
  template: `
    <div class="tool-panel-content">
      <div class="filter-section">
        <label class="filter-label">Department</label>
        <select class="filter-select" [(ngModel)]="selectedDepartment">
          <option value="">All Departments</option>
          @for (dept of departments; track dept) {
            <option [value]="dept">{{ dept }}</option>
          }
        </select>
      </div>

      <div class="filter-section">
        <label class="filter-label">Level</label>
        <div class="filter-pills">
          @for (level of levels; track level) {
            <label class="filter-pill" [class.filter-pill--active]="selectedLevels.includes(level)">
              <input
                type="checkbox"
                [checked]="selectedLevels.includes(level)"
                (change)="toggleLevel(level)"
              />
              <span>{{ level }}</span>
            </label>
          }
        </div>
      </div>

      <div class="filter-section">
        <label class="filter-label">Status</label>
        <div class="filter-pills">
          @for (status of statuses; track status) {
            <label
              class="filter-pill"
              [class.filter-pill--active]="selectedStatuses.includes(status)"
            >
              <input
                type="checkbox"
                [checked]="selectedStatuses.includes(status)"
                (change)="toggleStatus(status)"
              />
              <span>{{ status }}</span>
            </label>
          }
        </div>
      </div>

      <div class="filter-section">
        <label class="filter-label">Rating</label>
        <div class="filter-range">
          <input type="range" [(ngModel)]="minRating" min="0" max="5" step="0.5" />
          <span class="filter-range__value">≥ {{ minRating }}</span>
        </div>
      </div>

      <div class="filter-section">
        <label class="filter-checkbox">
          <input type="checkbox" [(ngModel)]="topPerformersOnly" />
          <span>⭐ Top Performers Only</span>
        </label>
      </div>

      <div class="filter-actions">
        <button class="btn-primary" (click)="applyFilters()">Apply Filters</button>
        <button class="btn-secondary" (click)="clearFilters()">Clear</button>
      </div>
    </div>
  `,
})
export class QuickFiltersPanelComponent implements OnInit {
  /** The grid element to apply filters to - properly typed! */
  grid = input.required<GridElement<Employee>>();

  readonly departments = DEPARTMENTS;
  readonly levels = ['Junior', 'Mid', 'Senior', 'Lead', 'Principal', 'Director'];
  readonly statuses = ['Active', 'Remote', 'On Leave', 'Contract', 'Terminated'];

  selectedDepartment = '';
  selectedLevels: string[] = [];
  selectedStatuses: string[] = [];
  minRating = 0;
  topPerformersOnly = false;

  ngOnInit(): void {
    // Initialize from current filter state if available
  }

  toggleLevel(level: string): void {
    const index = this.selectedLevels.indexOf(level);
    if (index >= 0) {
      this.selectedLevels.splice(index, 1);
    } else {
      this.selectedLevels.push(level);
    }
  }

  toggleStatus(status: string): void {
    const index = this.selectedStatuses.indexOf(status);
    if (index >= 0) {
      this.selectedStatuses.splice(index, 1);
    } else {
      this.selectedStatuses.push(status);
    }
  }

  applyFilters(): void {
    // No type casting needed - grid input is properly typed!
    const plugin = this.grid()?.getPlugin?.(FilteringPlugin);
    if (!plugin) return;

    plugin.clearAllFilters?.();

    if (this.selectedDepartment) {
      plugin.setFilter?.('department', {
        type: 'text',
        operator: 'equals',
        value: this.selectedDepartment,
      });
    }

    if (this.selectedLevels.length > 0) {
      plugin.setFilter?.('level', { type: 'set', operator: 'in', value: this.selectedLevels });
    }

    if (this.selectedStatuses.length > 0) {
      plugin.setFilter?.('status', { type: 'set', operator: 'in', value: this.selectedStatuses });
    }

    if (this.minRating > 0) {
      plugin.setFilter?.('rating', {
        type: 'number',
        operator: 'greaterThanOrEqual',
        value: this.minRating,
      });
    }

    if (this.topPerformersOnly) {
      plugin.setFilter?.('isTopPerformer', { type: 'boolean', operator: 'equals', value: true });
    }
  }

  clearFilters(): void {
    const plugin = this.grid()?.getPlugin?.(FilteringPlugin);
    plugin?.clearAllFilters?.();

    this.selectedDepartment = '';
    this.selectedLevels = [];
    this.selectedStatuses = [];
    this.minRating = 0;
    this.topPerformersOnly = false;
  }
}
```

```ts
// demos/angular/src/demos/employee-management/tool-panels/analytics-panel.component.ts
import { Component, computed, input } from '@angular/core';
import { type Employee, type GridElement } from '@demo/shared/employee-management';

/**
 * Analytics tool panel component.
 * Shows statistics about the employee data.
 */
@Component({
  selector: 'app-analytics-panel',
  template: `
    <div class="analytics-content">
      <div class="stat-cards">
        <div class="stat-card stat-card--payroll">
          <div class="stat-card__label">Total Payroll</div>
          <div class="stat-card__value">{{ formatCurrency(totalSalary()) }}</div>
        </div>
        <div class="stat-card stat-card--salary">
          <div class="stat-card__label">Avg Salary</div>
          <div class="stat-card__value">{{ formatCurrency(avgSalary()) }}</div>
        </div>
        <div class="stat-card stat-card--rating">
          <div class="stat-card__label">Avg Rating</div>
          <div class="stat-card__value">{{ avgRating().toFixed(1) }} ★</div>
        </div>
        <div class="stat-card stat-card--performers">
          <div class="stat-card__label">Top Performers</div>
          <div class="stat-card__value">{{ topPerformers() }}</div>
        </div>
      </div>

      <div class="dept-distribution">
        <h4 class="dept-distribution__title">Department Distribution</h4>
        <div class="dept-bars">
          @for (dept of topDepartments(); track dept.name) {
            <div class="dept-bar">
              <span class="dept-bar__name" [title]="dept.name">{{ dept.name }}</span>
              <div class="dept-bar__track">
                <div class="dept-bar__fill" [style.width.%]="dept.percentage"></div>
              </div>
              <span class="dept-bar__count">{{ dept.count }}</span>
            </div>
          }
        </div>
      </div>

      @if (largestDept(); as dept) {
        <div class="largest-dept">
          <div class="largest-dept__label">Largest Department</div>
          <div class="largest-dept__value">
            {{ dept.name }}
            <span class="largest-dept__count">({{ dept.count }} employees)</span>
          </div>
        </div>
      }
    </div>
  `,
})
export class AnalyticsPanelComponent {
  /** The grid element (properly typed) */
  grid = input.required<GridElement<Employee>>();

  /** Rows passed directly (for reactivity) */
  rows = input<Employee[]>([]);

  // Computed values
  totalSalary = computed(() => {
    const data = this.rows();
    return data.reduce((sum, r) => sum + r.salary, 0);
  });

  avgSalary = computed(() => {
    const data = this.rows();
    if (data.length === 0) return 0;
    return this.totalSalary() / data.length;
  });

  avgRating = computed(() => {
    const data = this.rows();
    if (data.length === 0) return 0;
    return data.reduce((sum, r) => sum + r.rating, 0) / data.length;
  });

  topPerformers = computed(() => {
    const data = this.rows();
    return data.filter((r) => r.isTopPerformer).length;
  });

  departmentCounts = computed(() => {
    const data = this.rows();
    const counts: Record<string, number> = {};
    data.forEach((r) => {
      counts[r.department] = (counts[r.department] || 0) + 1;
    });
    return Object.entries(counts)
      .map(([name, count]) => ({
        name,
        count,
        percentage: data.length > 0 ? (count / data.length) * 100 : 0,
      }))
      .sort((a, b) => b.count - a.count);
  });

  topDepartments = computed(() => this.departmentCounts().slice(0, 6));

  largestDept = computed(() => this.departmentCounts()[0] || null);

  formatCurrency(value: number): string {
    return value.toLocaleString('en-US', {
      style: 'currency',
      currency: 'USD',
      maximumFractionDigits: 0,
    });
  }
}
```

---

# Architecture

> Internal architecture of @toolbox-web/grid — configuration system, render scheduler, virtualization, plugin lifecycle, and light DOM design.

This page describes the internal architecture of `@toolbox-web/grid`. It's intended for contributors, plugin developers, and anyone who wants to understand how the grid works under the hood.

## Design Philosophy

1. **Light DOM** — No Shadow DOM. The grid renders directly into the element, allowing full CSS customization.
2. **Single Source of Truth** — All configuration converges into `effectiveConfig`, which is the only state read by rendering logic.
3. **Plugin-First** — Features like selection, editing, and filtering are plugins, not core code. This keeps the core small and tree-shakeable.
4. **Web Standards** — Built on Custom Elements, CSS Custom Properties, `adoptedStyleSheets`, and standard DOM APIs.
5. **Framework-Agnostic** — Pure TypeScript/HTML, no runtime framework dependencies.

## Component Overview

```
┌───────────────────────────────────────────────────────┐
│                        <tbw-grid>                     │
│  ┌─────────────────────────────────────────────────┐  │
│  │                    Light DOM                    │  │
│  │  ┌───────────────────────────────────────────┐  │  │
│  │  │              Header Row                   │  │  │
│  │  └───────────────────────────────────────────┘  │  │
│  │  ┌───────────────────────────────────────────┐  │  │
│  │  │           Rows Viewport (scrollable)      │  │  │
│  │  │  ┌─────────────────────────────────────┐  │  │  │
│  │  │  │  Spacer (virtual scroll height)     │  │  │  │
│  │  │  ├─────────────────────────────────────┤  │  │  │
│  │  │  │  Visible Rows (row pool)            │  │  │  │
│  │  │  └─────────────────────────────────────┘  │  │  │
│  │  └───────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────┘
```

## Component Lifecycle

```
constructor()
  └── Create internal state objects
  └── Initialize render scheduler

connectedCallback()
  └── Parse light DOM children (<tbw-grid-column>, <tbw-grid-header>)
  └── Merge configuration (gridConfig + columns + fitMode + light DOM)
  └── Attach plugins (validate dependencies, call onAttach)
  └── Render header + rows
  └── Set up scroll listener, resize observer

attributeChangedCallback()
  └── Map attribute → property setter

disconnectedCallback()
  └── Abort disconnect signal (plugins clean up)
  └── Remove event listeners
  └── Disconnect resize observer
```

---

## Configuration Architecture

The grid follows a **single source of truth** pattern. All configuration inputs converge into one `effectiveConfig` object, which is then used for all rendering and behavior.

### Why Single Source of Truth?

- **Predictable behavior**: One canonical config means no ambiguity about which setting applies
- **Easy debugging**: Inspect `effectiveConfig` to see exactly what the grid is using
- **Flexible input**: Users can configure via the method most convenient for their use case
- **Plugin-friendly**: Plugins can read/modify config through one consistent interface

### Input Sources

Users can configure the grid through multiple input methods:

```mermaid
flowchart TB
    subgraph inputs["INPUT SOURCES"]
        direction TB
        A["gridConfig<br/>property"]
        B["columns<br/>property"]
        C["fitMode<br/>property"]

        subgraph lightdom["LIGHT DOM"]
            D["&lt;tbw-grid-column&gt;<br/>field, header"]
            E["&lt;tbw-grid-header&gt;<br/>title"]
        end
    end

    A --> F
    B --> F
    C --> F
    D --> F
    E --> F

    F["ConfigManager.merge()<br/><i>single merge point</i>"]
    F --> G["#effectiveConfig<br/><i>canonical config</i><br/>◀ SINGLE SOURCE OF TRUTH"]
    G --> H["DERIVED STATE<br/>_columns (processed)<br/>_rows (processed)"]
```

### Precedence Rules

When the same property is set via multiple sources, higher precedence wins:

| Priority    | Source                | Example                                      |
| ----------- | --------------------- | -------------------------------------------- |
| 1 (lowest)  | `gridConfig` property | `grid.gridConfig = { fitMode: 'stretch' }`   |
| 2           | Light DOM elements    | `<tbw-grid-column field="name">`             |
| 3           | `columns` property    | `grid.columns = [{ field: 'name' }]`         |
| 4           | Inferred columns      | (auto-detected from first row)               |
| 5 (highest) | Individual props      | `grid.fitMode = 'fixed'`                     |

> **Note:** HTML attributes (`rows`, `columns`, `grid-config`, `fit-mode`) invoke the corresponding property setters via `attributeChangedCallback` — they are not a separate precedence layer.

### HTML Attribute Configuration

The grid supports JSON-serialized configuration via HTML attributes:

```html
<tbw-grid
  rows='[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]'
  columns='[{"field":"id","header":"ID"},{"field":"name","header":"Name"}]'
  fit-mode="stretch"
>
</tbw-grid>
```

Supported attributes: `rows`, `columns`, `grid-config`, `fit-mode`.

### Light DOM Configuration

The grid parses these light DOM elements on connection:

```html
<tbw-grid>
  <!-- Column definitions (→ effectiveConfig.columns) -->
  <tbw-grid-column field="name" header="Name" sortable></tbw-grid-column>
  <tbw-grid-column field="age" header="Age" type="number"></tbw-grid-column>

  <!-- Shell header (→ effectiveConfig.shell.header) -->
  <tbw-grid-header title="My Data Grid">
    <tbw-grid-header-content>
      <span>Custom content here</span>
    </tbw-grid-header-content>
    <tbw-grid-tool-buttons>
      <button class="tbw-toolbar-btn" title="Refresh">🔄</button>
    </tbw-grid-tool-buttons>
  </tbw-grid-header>
</tbw-grid>
```

### Internal State Categories

| Category | Example | Description |
|----------|---------|-------------|
| **Input Properties** | `#rows`, `#columns`, `#gridConfig`, `#fitMode` | Raw user input, stored as-is |
| **Effective Config** | `#effectiveConfig` | Merged canonical config — single source of truth |
| **Derived State** | `_columns`, `_rows` | Post-plugin-processing state used by rendering |
| **Runtime State** | `#hiddenColumns`, `sortState` | User-driven state changes (hide column, sort, etc.) |

**Key rule:** Rendering logic reads from `effectiveConfig` or derived state, never from input properties.

---

### Two-Layer Config Architecture

ConfigManager implements a two-layer architecture to separate the **original configuration** (from sources) from **runtime mutations**:

```mermaid
flowchart TB
    subgraph sources["SOURCES"]
        A["gridConfig"]
        B["columns"]
        C["fitMode"]
        D["Light DOM"]
        E["Shell State Maps"]
    end

    A --> F
    B --> F
    C --> F
    D --> F
    E --> F

    F["ConfigManager.merge()"]
    F -->|"sources changed"| G["#originalConfig<br/><i>(frozen, immutable)</i>"]
    G -->|"clone"| H["#effectiveConfig<br/><i>(mutable, runtime changes)</i>"]

    H -->|"user interaction"| I["Runtime Mutations<br/>hidden, width, sort order"]

    J["resetState()"] -->|"clone original → effective"| H
```

**Layer 1: Original Config (`#originalConfig`)**

- Built from all sources via `#collectAllSources()`
- Frozen after creation (`Object.freeze`)
- Immutable — never modified after merge
- Serves as the "reset point" for the effective config

**Layer 2: Effective Config (`#effectiveConfig`)**

- Deep cloned from original config
- Mutable — runtime changes go here
- Column visibility, widths, sort order, etc.
- All rendering reads from this layer

**Key Behaviors:**

| Operation                                 | What Happens                                               |
| ----------------------------------------- | ---------------------------------------------------------- |
| Source changes (gridConfig, columns, etc.) | `markSourcesChanged()` → `merge()` rebuilds both layers   |
| Runtime mutation (hide column, resize)     | Modify `effectiveConfig` only, `original` untouched        |
| `resetState()`                             | Clone `original` → `effective`, discarding runtime changes |
| `collectState()`                           | Diff `effective` vs `original` to get user changes         |

**When Sources Change:**

Sources are re-collected only when `#sourcesChanged` is `true` AND columns already exist:

1. Setting `gridConfig`, `columns`, `fitMode` → auto-marks sources changed
2. Setting Light DOM columns → auto-marks sources changed
3. Shell state updates → call `markSourcesChanged()` explicitly
4. `merge()` is a no-op if sources haven't changed AND columns exist
5. If no columns exist yet, `merge()` always runs (to allow inference from rows)

This optimization prevents unnecessary rebuilds when `merge()` is called multiple times per frame.

---

## Rendering Pipeline

All rendering flows through a centralized **RenderScheduler** that batches all work into a single `requestAnimationFrame` callback. This eliminates race conditions between different parts of the grid that previously scheduled independent RAFs.

### Render Scheduler Architecture

```mermaid
flowchart TB
    subgraph sources["RENDER REQUESTS"]
        A["Property Change<br/>(rows, columns, gridConfig)"]
        B["Framework Adapter<br/>(React/Angular refreshColumns)"]
        C["ResizeObserver<br/>(container resize)"]
        D["Scroll Event<br/>(virtualization)"]
        E["Plugin Request<br/>(afterRender needs)"]
    end

    A --> F["RenderScheduler.requestPhase()"]
    B --> F
    C --> F
    D --> G["Direct Call<br/>(hot path)"]
    E --> F

    F --> H["Single RAF<br/>#flush()"]
    H --> I["Phase-Ordered Execution"]

    subgraph phases["EXECUTION ORDER (data dependencies)"]
        P1["1. mergeConfig<br/>(FULL/COLUMNS phase)"]
        P2["2. processRows<br/>(ROWS phase)"]
        P3["3. processColumns + updateTemplate<br/>(COLUMNS phase)"]
        P4["4. renderHeader<br/>(HEADER phase)"]
        P5["5. refreshVirtualWindow<br/>(VIRTUALIZATION phase)"]
        P6["6. afterRender hooks<br/>(STYLE phase)"]
    end

    I --> P1 --> P2 --> P3 --> P4 --> P5 --> P6
```

### Render Phases

Work is organized into ordered phases. Multiple requests merge to the **highest requested phase**:

| Phase | Priority | Work Performed |
|-------|----------|----------------|
| `STYLE` | 1 | Plugin `afterRender()` hooks only |
| `VIRTUALIZATION` | 2 | Recalculate virtual window (+ STYLE) |
| `HEADER` | 3 | Re-render header row (+ VIRTUALIZATION) |
| `ROWS` | 4 | Rebuild row model (+ HEADER) |
| `COLUMNS` | 5 | Process columns, update CSS template (+ ROWS) |
| `FULL` | 6 | Merge effective config (+ COLUMNS) |

Higher phases implicitly cover all lower phases. Requesting `COLUMNS` when `ROWS` is already pending results in just `COLUMNS` executing.

**Example**: If React adapter requests `COLUMNS` and ResizeObserver requests `VIRTUALIZATION` in the same frame, only `COLUMNS` phase runs (which includes all lower phases).

### Execution Order in `#flush()`

```typescript
if (phase >= RenderPhase.COLUMNS) mergeConfig();
if (phase >= RenderPhase.ROWS)    processRows();
if (phase >= RenderPhase.COLUMNS) processColumns();
if (phase >= RenderPhase.COLUMNS) updateTemplate();
if (phase >= RenderPhase.HEADER)  renderHeader();
if (phase >= RenderPhase.VIRTUALIZATION) renderVirtualWindow();
if (phase >= RenderPhase.STYLE)   afterRender();
```

### Intentional Bypasses

Some operations intentionally bypass the scheduler for performance:

| Operation              | Reason                                     |
| ---------------------- | ------------------------------------------ |
| Scroll rendering       | Hot path — must be synchronous for 60fps   |
| Shell rebuild          | Creates DOM structure, not content updates |
| Row height measurement | One-time post-paint measurement            |

### Debugging Renders

The scheduler is held on a private field (`#scheduler`), so direct introspection from the console is not part of the public API. To trace render activity:

- Use the browser **Performance** tab and record around the interaction — each `requestAnimationFrame` callback shows up with the phase work (`processRows`, `processColumns`, `renderHeader`, `renderVirtualWindow`, plugin `afterRender`).
- Add `console.log` calls in your own plugin's hooks to confirm which phase fires after a given input.
- The `source` argument passed to `requestPhase()` (e.g., `'applyGridConfigUpdate'`, `'resize-observer'`, `'plugin:requestRender'`) is preserved for future debug surfaces; the strings are visible in source files when grepping for `requestPhase(`.

---

## Virtualization

### Row Virtualization (Built-in)

The grid maintains a "virtual window" — an offset and count representing which rows are visible:

```
Total rows: 10,000
Viewport: 400px, rowHeight: 28px → ~14 visible rows
Overscan: 8 rows above + 8 below = 30 DOM rows in pool

Scroll position: 5,000px → startIndex: 178
Rendered: rows 170–200 (30 rows in DOM)
```

- **Row pool**: DOM rows are reused, not created/destroyed on scroll
- **Transform-based positioning**: Each row uses `transform: translateY()` for GPU-accelerated positioning
- **Range-based updates**: Only rows entering/leaving the viewport get updated content

For very small datasets (≤8 rows by default), virtualization is bypassed — the overhead isn't worth it.

#### Massive datasets and the browser height cap

Browsers cap a single element's rendered height at roughly **33.5M px** (Chromium's `2^25`; Firefox/Safari are similar). With the default `rowHeight: 34`, that's hit at about **986,895 rows**. Above the cap, the faux-vscroll spacer would silently truncate, leaving the tail of the dataset unreachable.

To support datasets exceeding the cap (e.g. log viewers with 10M+ rows), the grid switches to **fractional scroll mapping**:

- The spacer is clamped at `MAX_ELEMENT_HEIGHT_PX` (≈ 33.5M px).
- The native `scrollTop` is treated as a position in the clamped spacer space and translated into a **virtual** offset in raw row-content space:
  ```text
  virtualScrollTop = scrollTop * (rawContentHeight − viewport) / (spacerHeight − viewport)
  ```
- `scrollToRow(N)` reverse-maps the row's offset back into the spacer's `scrollTop` so any row in the dataset is reachable programmatically.

For datasets below the cap, mapping is identity — pixel-accurate behavior is unchanged. Above the cap, every row remains reachable via the scrollbar, `Ctrl+End`, and `scrollToRow(N)`. Keyboard cell navigation (`ArrowDown`/`ArrowUp`/`Tab`/`PageDown`/`PageUp`) also stays single-row accurate — focus moves by row index and the auto-scroll that keeps the focused cell visible routes through the mapping. The remaining caveat is **direct scroll input** (mouse wheel, scrollbar drag, `Space`/`Shift+Space`): one pixel of `scrollTop` corresponds to many rows above the cap, so a single wheel notch can skip past hundreds of rows. The mapping helpers (`MAX_ELEMENT_HEIGHT_PX`, `computeScrollMapping`, `toVirtualScrollTop`, `fromVirtualScrollTop`) are exported for plugins that maintain their own scroll-driven DOM state.

### Column Virtualization (Plugin)

The `ColumnVirtualizationPlugin` applies the same window concept horizontally. Only columns visible in the horizontal scroll position are rendered.

---

## Plugin System & Feature Registry

The plugin lifecycle, hooks, manifest schema, validated properties, communication channels, and the feature registry are documented under [Plugin Development → Architecture](/grid/plugin-development/architecture.md). That page also covers tree-shaking, dependency ordering, and the lazy-hook design that keeps the feature API zero-cost when unused.

For a step-by-step tutorial on building your own plugin, see the [Authoring Guide](/grid/plugin-development/custom-plugins.md).

---

## Framework Adapter System

How React, Angular, and Vue adapters intercept cell rendering, editor creation, config processing, and cell cleanup is documented under [Framework Adapters → Architecture](/grid/framework-adapters/architecture.md).

---

## Shell System

The **shell** is an optional wrapper that adds a header bar, toolbar buttons, and a collapsible tool panel sidebar to the grid.

### Structure

```
┌──────────────────────────────────────────────────────────┐
│ SHELL HEADER                                             │
│ ┌──────────┬──────────────────┬────────────────────────┐ │
│ │  Title   │  Header Content  │  Toolbar  │ ☰ Toggle  │ │
│ └──────────┴──────────────────┴────────────────────────┘ │
├───────────┬──────────────────────────────────────────────┤
│ TOOL      │                                              │
│ PANEL     │              GRID CONTENT                    │
│ (sidebar) │                                              │
│ ┌───────┐ │   ┌─────────────────────────────────────┐    │
│ │Section│ │   │  Header Row                         │    │
│ │  ▼    │ │   ├─────────────────────────────────────┤    │
│ │Content│ │   │  Data Rows (virtualized)            │    │
│ │       │ │   │                                     │    │
│ ├───────┤ │   └─────────────────────────────────────┘    │
│ │Section│ │                                              │
│ │  ▶   │ │                                              │
│ └───────┘ │                                              │
└───────────┴──────────────────────────────────────────────┘
```

### Configuration

The shell is configured via `gridConfig.shell` or Light DOM elements:

```typescript
gridConfig: {
  shell: {
    header: { title: 'My Grid' },
    toolPanel: {
      position: 'left' | 'right',  // Sidebar position
      width: '17.5em',             // Panel width (CSS value)
      defaultOpen: 'filters',      // Section auto-expanded on first open (v2: also opens sidebar — deprecated, see #259)
      initialState: 'closed',      // 'open' | 'closed' — preferred way to control sidebar open state
      locked: false,               // true = sidebar always open, toggle hidden
      closeOnClickOutside: false,
    },
  },
}
```

Or declaratively:

```html
<tbw-grid>
  <tbw-grid-header title="My Grid">
    <tbw-grid-header-content>
      <span>Custom center content</span>
    </tbw-grid-header-content>
    <tbw-grid-tool-buttons>
      <button class="tbw-toolbar-btn" title="Export">📥</button>
    </tbw-grid-tool-buttons>
  </tbw-grid-header>
</tbw-grid>
```

### Content Types

Plugins and application code can register three types of content:

| Type | Location | Example |
|------|----------|---------|
| **ToolPanel** | Accordion sections in sidebar | Filter panel, visibility panel, pivot config |
| **HeaderContent** | Center of header bar | Search box, breadcrumbs |
| **ToolbarContent** | Right side of header (before toggle) | Export button, view switcher |

Each content type uses a render function pattern:

```typescript
grid.getPluginByName('shell')?.registerToolPanel({
  id: 'filters',
  title: 'Filters',
  icon: '🔍',
  render: (container) => {
    container.innerHTML = '<div>Filter UI here</div>';
    return () => { /* cleanup */ };
  },
});
```

### Shell State

The shell maintains runtime state for:

- **Panel open/close** — `isPanelOpen`, toggled via `openToolPanel()` / `closeToolPanel()`
- **Expanded sections** — `expandedSections: Set<string>`, accordion state
- **Content registrations** — `toolPanels`, `headerContents`, `toolbarContents` Maps
- **Cleanup functions** — Each rendered content can return a cleanup callback, tracked for disposal

### Lazy Rendering

Tool panel section content is rendered **lazily** — the `render()` function only executes when the user expands that accordion section for the first time. This avoids expensive initialization for panels the user never opens.

---

## Animation System

The grid supports CSS-driven animations for row insert, remove, and update operations.

### Animation Types

| Type | Trigger | Default Duration | CSS Variable |
|------|---------|-----------------|--------------|
| `'insert'` | `insertRow()`, bulk add | 300ms | `--tbw-row-insert-duration` |
| `'remove'` | `removeRow()`, bulk delete | 200ms | `--tbw-row-remove-duration` |
| `'change'` | `animateRow()`, data update highlight | 500ms | `--tbw-row-change-duration` |

### How It Works

Animations use a **CSS attribute hook** pattern:

1. Grid sets `data-animating="insert"` on the row element
2. CSS transitions/keyframes in `grid.css` target `[data-animating="insert"]`
3. After the duration, a `setTimeout` removes the attribute (or the row for `'remove'`)
4. A `Promise` resolves when the animation completes

```typescript
// Core mechanism (row-animation.ts)
rowEl.setAttribute('data-animating', animationType);
const duration = getAnimationDuration(rowEl, animationType);
setTimeout(() => {
  if (animationType !== 'remove') {
    rowEl.removeAttribute('data-animating');
  }
  onComplete?.();
}, duration);
```

### Animation Configuration

```typescript
gridConfig: {
  animation: {
    mode: 'reduced-motion',  // Default: respects prefers-reduced-motion
    duration: 200,           // Sets --tbw-animation-duration
    easing: 'ease-out',      // Sets --tbw-animation-easing
  },
}
```

**`mode` options:**

| Value | Behavior |
|-------|----------|
| `true` / `'on'` | Always animate |
| `false` / `'off'` | Never animate |
| `'reduced-motion'` | Respect `prefers-reduced-motion` media query (default) |

### Public API

```typescript
// Highlight a row after data update
await grid.animateRow(5, 'change');

// Highlight by row ID
await grid.animateRowById('emp-123', 'change');

// Animate multiple rows
const count = await grid.animateRows([0, 2, 5], 'change');

// Insert with auto-animation (default)
await grid.insertRow(0, newRow);         // Animates
await grid.insertRow(0, newRow, false);  // No animation

// Remove with auto-animation (default)
const removed = await grid.removeRow(5);         // Animates fade-out
const removed = await grid.removeRow(5, false);  // Immediate
```

All methods return `Promise`s — `await` ensures the animation completes before proceeding.

### CSS Customization

Override animation timing per-type via CSS custom properties:

```css
tbw-grid {
  --tbw-row-change-duration: 800ms;   /* Longer highlight */
  --tbw-row-insert-duration: 0ms;     /* Disable insert animation */
  --tbw-row-remove-duration: 150ms;   /* Faster fade-out */
  --tbw-row-change-color: #fff3cd;    /* Yellow highlight */
}

---

## DOM Structure

```html
<tbw-grid aria-label="..." role="grid">
  <div class="data-grid-container">
    <!-- Header -->
    <div role="rowgroup">
      <div role="row" aria-rowindex="1">
        <div role="columnheader" aria-colindex="1">Name</div>
        <div role="columnheader" aria-colindex="2">Age</div>
      </div>
    </div>

    <!-- Body (scrollable, virtualized) -->
    <div role="rowgroup" class="data-grid-body">
      <div role="row" aria-rowindex="2" style="transform: translateY(0px)">
        <div role="gridcell" aria-colindex="1">Alice</div>
        <div role="gridcell" aria-colindex="2">30</div>
      </div>
    </div>
  </div>
</tbw-grid>
```

---

## Styling Architecture

### CSS Custom Properties

All styling uses CSS custom properties for theming. Override defaults to customize:

```css
tbw-grid {
  --tbw-color-bg: #ffffff;
  --tbw-color-fg: #1a1a1a;
  --tbw-color-border: #e5e5e5;
  --tbw-color-header-bg: #f5f5f5;
  --tbw-row-height: 1.75em;    /* ~28px at 16px font */
  --tbw-header-height: 1.875em; /* ~30px at 16px font */
  --tbw-font-family: system-ui, sans-serif;
  --tbw-font-size: 1em;
}
```

### Key CSS Architecture

- **CSS Nesting**: Styles use `tbw-grid { .data-grid-container { ... } }` for scoping
- **Cascade Layers**: `@layer tbw-base, tbw-plugins, tbw-theme` — user styles always win
- **Adopted Stylesheets**: Dynamic styles use `document.adoptedStyleSheets` for efficiency — styles survive `replaceChildren()` calls
- **`em`-Based Sizing**: Row height, padding, and spacing scale with `font-size`

### Plugin Styles

Plugins inject CSS via their `styles` property using adopted stylesheets. They use a layered fallback pattern for flexibility:

```css
/* Plugin-specific → Global fallback */
background: var(--tbw-selection-bg, var(--tbw-color-selection));
```

---

## Event Flow

The grid dispatches `CustomEvent`s for every user-visible action (cell clicks, commits, sort changes, etc.). See the [Events section of the API Reference](/grid/api-reference/#events) for the full list and the auto-generated [`DataGridEventMap`](/grid/api/core/interfaces/datagrideventmap/) for payload types.

Internally, plugins communicate through two mechanisms described in the [Plugin Communication](#plugin-communication) section above: the **Event Bus** (async, fire-and-forget) and the **Query System** (sync, request-response). Public `CustomEvent`s are dispatched by the core grid or by individual plugins after their internal processing completes.

### Data Flow Example: Sort

```
User clicks sort header
  ↓
Header click handler → update sortState
  ↓
Call processRows() on all plugins (MultiSortPlugin sorts)
  ↓
_rows updated with sorted order
  ↓
scheduler.requestPhase(ROWS, 'sort')
  ↓
requestAnimationFrame
  ↓
Render: update visible row content from new _rows
```

---

## Performance

### DOM Optimization

| Technique | Benefit |
| --- | --- |
| **Template Cloning** | 3–4× faster than `createElement` |
| **Direct DOM Construction** | Avoids innerHTML parsing overhead |
| **DocumentFragment** | Single reflow per row |
| **Row Pooling** | Zero allocation during scroll |
| **Cached DOM Refs** | Avoid querySelector per scroll |

### Rendering Pipeline

| Technique | Benefit |
| --- | --- |
| **Centralized Scheduler** | Eliminates race conditions |
| **Phase-Based Execution** | No duplicate work |
| **adoptedStyleSheets** | Runtime CSS injection without child node removal |
| **Idle Scheduling** | Faster time-to-interactive |
| **Fast-Path Patching** | Skip expensive template logic for plain text |
| **Cell Display Cache** | Avoid recomputing during scroll |

### Event Handling

| Technique | Benefit |
| --- | --- |
| **Event Delegation** | Constant memory regardless of rows |
| **Pooled Scroll Events** | Zero GC pressure during scroll |
| **AbortController Cleanup** | No memory leaks on disconnect |

---

## Directory Structure

```
libs/grid/src/
├─ index.ts                # Main entry (auto-registers element)
├─ public.ts               # Public API surface (types, constants)
├─ all.ts                  # All-in-one bundle with all plugins
└─ lib/
   ├─ core/
   │  ├─ grid.ts             # Main component class (~4500 lines)
   │  ├─ grid.css            # Core styles
   │  ├─ types.ts            # Public type definitions
   │  ├─ constants.ts        # DOM class/attribute constants
   │  ├─ internal/           # Pure helper functions
   │  │  ├─ columns.ts        # Column resolution, sizing
   │  │  ├─ config-manager.ts # Two-layer config (original + effective)
   │  │  ├─ dom-builder.ts    # Direct DOM construction
   │  │  ├─ render-scheduler.ts # RAF-based render batching
   │  │  ├─ rows.ts           # Row rendering + cell patching
   │  │  ├─ row-animation.ts  # CSS-driven row animations
   │  │  ├─ shell.ts          # Shell header, toolbar, tool panels
   │  │  ├─ virtualization.ts # Virtual scroll math
   │  │  ├─ feature-hook.ts   # Lazy bridge to feature registry
   │  │  └─ ...              # More internal helpers
   │  ├─ plugin/             # Plugin infrastructure
   │  │  ├─ base-plugin.ts    # Abstract base class
   │  │  └─ plugin-manager.ts # Plugin lifecycle
   │  └─ styles/             # Core CSS (variables, layers)
   │     └─ variables.css     # CSS custom property defaults
   ├─ features/              # Feature registry (declarative plugin API)
   │  ├─ registry.ts          # registerFeature(), createPluginsFromFeatures()
   │  ├─ selection.ts         # Side-effect: registers selection feature
   │  ├─ editing.ts           # Side-effect: registers editing feature
   │  └─ ...                 # 25 feature modules total
   └─ plugins/               # Built-in plugins
      ├─ editing/             # Inline cell editing
      ├─ filtering/           # Column filters
      ├─ selection/           # Row/cell/range selection
      ├─ multi-sort/          # Multi-column sorting
      └─ ...                 # 24 plugins total
```

## See Also

- [Custom Plugins](/grid/plugin-development/custom-plugins.md) — Build your own plugins with hooks, events, and queries
- [Performance Guide](/grid/guides/performance.md) — Render scheduler tuning, virtualization, idle scheduling
- [Plugins Overview](/grid/plugins.md) — Available plugins and their hooks
- [Theming Guide](/grid/guides/theming.md) — CSS custom properties, themes, cascade layers
- [API Reference](/grid/api-reference.md) — Properties, methods, events, and types

---

# API Reference

> Complete reference for the <tbw-grid> component — properties, methods, events, CSS custom properties, keyboard shortcuts, declarative configuration, and accessibility.

Complete reference for the `<tbw-grid>` component API.

## Element Tag

```html
<tbw-grid></tbw-grid>
```

The custom element is registered as `tbw-grid` (Toolbox Web Grid).

## Properties

### Core Data Properties

| Property     | Type             | Default | Description                |
| ------------ | ---------------- | ------- | -------------------------- |
| `rows`       | `T[]`            | `[]`    | Array of row data objects  |
| `columns`    | [`ColumnConfig[]`](/grid/api/core/interfaces/columnconfig.md) | `[]`    | Column configuration array |
| `gridConfig` | [`GridConfig<T>`](/grid/api/core/interfaces/gridconfig.md)  | `{}`    | Full configuration object  |

### Layout Properties

| Property  | Type                   | Default     | Description            |
| --------- | ---------------------- | ----------- | ---------------------- |
| `fitMode` | `'stretch' \| 'fixed'` | `'stretch'` | Column sizing strategy |

### State Properties

| Property      | Type                        | Default | Description                                 |
| ------------- | --------------------------- | ------- | ------------------------------------------- |
| `loading`     | `boolean`                   | `false` | Grid-level loading state. Customise the indicator via [`gridConfig.loadingRenderer`](/grid/api/core/types/loadingrenderer.md) |
| `columnState` | [`GridColumnState[]`](/grid/api/core/interfaces/gridcolumnstate.md)         | -       | Get/set column widths, order, visibility, sort |

### Read-only Properties

| Property      | Type                         | Description                   |
| ------------- | ---------------------------- | ----------------------------- |
| `changedRows` | `T[]`                        | Rows with pending edits (requires EditingPlugin) |
| `sortState`   | `Map<string, `[`SortState`](/grid/api/core/interfaces/sortstate.md)`>`     | Current sort state per column |

## Declarative Configuration

The grid supports two forms of declarative HTML configuration:

1. **HTML Attributes** — JSON-serialized values on the `<tbw-grid>` element itself
2. **Light DOM Elements** — Child elements nested inside `<tbw-grid>` for more readable markup

Both approaches can be combined. Light DOM elements take precedence over JSON attributes for the same configuration (e.g., `<tbw-grid-column>` elements override the `columns` attribute).

:::note
JavaScript property assignment always takes precedence over declarative configuration. Removing an attribute or element does not clear a JS-set value.
:::

### HTML Attributes

Attributes on the `<tbw-grid>` element for simple or programmatically-generated configuration:

| Attribute     | Maps to Property | Type   | Description                |
| ------------- | ---------------- | ------ | -------------------------- |
| `rows`        | `rows`           | JSON   | Row data as JSON array     |
| `columns`     | `columns`        | JSON   | Column config as JSON array|
| `grid-config` | `gridConfig`     | JSON   | Full config object as JSON |
| `fit-mode`    | `fitMode`        | string | `'stretch'` or `'fixed'`   |

```html
<tbw-grid
  rows='[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]'
  columns='[{"field":"id","header":"ID"},{"field":"name","header":"Name"}]'
  fit-mode="stretch"
></tbw-grid>
```

### Plugin Host Attributes (`data-*`)

Some plugins read their own `data-*` attributes directly from the `<tbw-grid>` host
element when they attach. These are namespaced under `data-` to avoid colliding with
the grid's own reactive attributes (`rows`, `columns`, `grid-config`, `fit-mode`,
`loading`). They are read **once at attach time** — changing them afterward has no
effect (use the JSON `grid-config` attribute or a JS property for reactive updates).

| Attribute  | Owning plugin      | Description                                                                                         |
| ---------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| `data-src` | [`ServerSidePlugin`](/grid/plugins/server-side.md) | URL to fetch row data from — enables a zero-JS server-fetched grid. See [Server-Side → Declarative `data-src`](/grid/plugins/server-side.md#declarative-data-src-zero-js). |

### Light DOM Elements

Child elements inside `<tbw-grid>` for more readable, template-friendly configuration. Preferred for framework templates (Angular, Vue, etc.) and complex column setups with custom renderers/editors.

#### Column Elements

##### `<tbw-grid-column>`

Define column configuration declaratively.

| Attribute      | Type      | Description                                                      |
| -------------- | --------- | ---------------------------------------------------------------- |
| `field`        | `string`  | **Required.** Data field key                                     |
| `header`       | `string`  | Column header text                                               |
| `type`         | `string`  | Column type. Built-ins: `'string'`, `'number'`, `'boolean'`, `'date'`, `'select'`. Any custom/plugin-registered type string is also accepted. |
| `width`        | `string`  | Column width (e.g., `"120"`, `"100px"`, `"20%"`)                 |
| `min-width`    | `number`  | Minimum column width in pixels                                   |
| `sortable`     | `boolean` | Enable sorting (presence = true)                                 |
| `resizable`    | `boolean` | Enable resizing (presence = true)                                |
| `order`        | `number`  | Initial column position (0-based index; must be non-negative integer). Columns without `order` fill positions in declaration order. Only affects initial render; user reorder takes precedence. |
| `editable`     | `boolean` | Enable editing (presence = true, requires EditingPlugin)         |
| `options`      | `string`  | Select options: `"value1:Label1,value2:Label2"` or `"val1,val2"` |
| `pinned`       | `string`  | Pin the column to an edge: `'left'` / `'start'` or `'right'` / `'end'` (requires PinnedColumnsPlugin). |
| `hidden`       | `boolean` | Hide the column initially (presence = true; `hidden="false"` keeps it visible). Requires VisibilityPlugin. |
| `lock-visible` | `boolean` | Prevent the column from being hidden via the visibility panel (presence = true). Requires VisibilityPlugin. |

> Plugin-contributed attributes (`pinned`, `hidden`, `lock-visible`, `editable`, `<tbw-grid-column-editor>`) are read by their owning plugin when it is registered. They set the column's **initial** state — subsequent runtime changes (e.g. `setColumnVisible()`, drag-to-pin) take precedence.

```html
<tbw-grid>
  <tbw-grid-column field="id" header="ID" type="number" width="80" order="0"></tbw-grid-column>
  <tbw-grid-column field="name" header="Name" sortable resizable order="1"></tbw-grid-column>
  <tbw-grid-column field="role" type="select" options="admin:Admin,user:User" order="2"></tbw-grid-column>
</tbw-grid>
```

##### `<tbw-grid-column-view>`

Custom view template inside a column. Content is used as the cell renderer.

```html
<tbw-grid-column field="status">
  <tbw-grid-column-view>
    <span class="badge">{{ value }}</span>
  </tbw-grid-column-view>
</tbw-grid-column>
```

##### `<tbw-grid-column-editor>`

Custom editor template inside a column (requires EditingPlugin).

```html
<tbw-grid-column field="name" editable>
  <tbw-grid-column-editor>
    <input type="text" />
  </tbw-grid-column-editor>
</tbw-grid-column>
```

##### `<tbw-grid-column-header>`

Custom header template inside a column.

```html
<tbw-grid-column field="status">
  <tbw-grid-column-header>
    <strong>Status</strong> <span class="required">*</span>
  </tbw-grid-column-header>
</tbw-grid-column>
```

#### Shell Elements

##### `<tbw-grid-header>`

Configure the shell header bar.

| Attribute | Type     | Description              |
| --------- | -------- | ------------------------ |
| `title`   | `string` | Grid title (left side)   |

```html
<tbw-grid>
  <tbw-grid-header title="Employee Directory">
    <tbw-grid-header-content>
      <span>20 employees</span>
    </tbw-grid-header-content>
  </tbw-grid-header>
</tbw-grid>
```

##### `<tbw-grid-header-content>`

Custom content in the shell header center area. Must be nested inside `<tbw-grid-header>`.

```html
<tbw-grid-header title="My Grid">
  <tbw-grid-header-content>
    <input type="search" placeholder="Search..." />
  </tbw-grid-header-content>
</tbw-grid-header>
```

##### `<tbw-grid-tool-buttons>`

Container for toolbar buttons (right side of shell header).

```html
<tbw-grid>
  <tbw-grid-tool-buttons>
    <button class="tbw-toolbar-btn" title="Export">📥</button>
    <button class="tbw-toolbar-btn" title="Print">🖨️</button>
  </tbw-grid-tool-buttons>
</tbw-grid>
```

#### Tool Panel Elements

##### `<tbw-grid-tool-panel>`

Define a custom tool panel for the sidebar.

| Attribute | Type     | Description                                    |
| --------- | -------- | ---------------------------------------------- |
| `id`      | `string` | **Required.** Unique panel identifier          |
| `title`   | `string` | **Required.** Panel title in accordion header  |
| `icon`    | `string` | Icon for accordion header (emoji or text)      |
| `tooltip` | `string` | Tooltip for accordion header                   |
| `order`   | `number` | Panel order priority (lower = first, default: 100) |

```html
<tbw-grid>
  <tbw-grid-tool-panel id="filters" title="Filters" icon="🔍" order="10">
    <div class="filter-panel">
      <label>Status: <select>...</select></label>
    </div>
  </tbw-grid-tool-panel>
</tbw-grid>
```

#### Plugin-Specific Elements

##### `<tbw-grid-detail>` (MasterDetailPlugin)

Define the detail panel template for master-detail rows. Requires the MasterDetailPlugin.

| Attribute             | Type                          | Description                                          |
| --------------------- | ----------------------------- | ---------------------------------------------------- |
| `animation`           | `'slide' \| 'fade' \| false` | Panel expand/collapse animation (default: `'slide'`) |
| `show-expand-column`  | `boolean`                     | Show expand/collapse column (default: `true`)        |
| `expand-on-row-click` | `boolean`                     | Expand when row clicked (default: `false`)           |
| `height`              | `number \| 'auto'`           | Panel height in pixels or auto (default: `'auto'`)   |

```html
<tbw-grid>
  <tbw-grid-detail animation="slide" expand-on-row-click="true">
    <div class="detail-panel">
      <h3>{{ row.name }}</h3>
      <p>{{ row.description }}</p>
    </div>
  </tbw-grid-detail>
</tbw-grid>
```

See the [MasterDetailPlugin documentation](/grid/plugins/master-detail.md) for more details.

##### `<tbw-grid-responsive-card>` (ResponsivePlugin)

Define a custom card template for responsive mode. Requires the ResponsivePlugin.

| Attribute         | Type                 | Description                                             |
| ----------------- | -------------------- | ------------------------------------------------------- |
| `breakpoint`      | `number`             | Width threshold in pixels for responsive mode           |
| `card-row-height` | `number \| 'auto'`   | Card height in pixels or auto (default: `'auto'`)       |
| `hidden-columns`  | `string`             | Comma-separated field names to hide in card mode        |
| `hide-header`     | `boolean`            | Hide header row in responsive mode (default: `true`)    |
| `debounce-ms`     | `number`             | Resize debounce delay in ms (default: `100`)            |

```html
<tbw-grid>
  <tbw-grid-responsive-card breakpoint="500" card-row-height="80" hidden-columns="createdAt, updatedAt">
    <div class="custom-card">
      <strong>{{ row.name }}</strong>
      <span>{{ row.email }}</span>
    </div>
  </tbw-grid-responsive-card>
</tbw-grid>
```

See the [ResponsivePlugin documentation](/grid/plugins/responsive.md) for more details.

:::note
Framework adapters may provide wrapper components for these elements. For example, `@toolbox-web/grid-react` provides `<GridResponsiveCard>` and `<GridDetailPanel>` React components with render prop support. See the [React adapter docs](/grid/react/getting-started.md) for details.
:::

## Helper Functions

```typescript
import { createGrid, queryGrid } from '@toolbox-web/grid';

// Create a new grid element with configuration
const grid = createGrid<Employee>({
  columns: [{ field: 'name' }, { field: 'email' }],
  fitMode: 'stretch',
});
document.body.appendChild(grid);
grid.rows = employees;

// Query an existing grid with type safety
const existingGrid = queryGrid<Employee>('#my-grid');
if (existingGrid) {
  existingGrid.rows = newData;
}
```

## Methods

### Data Methods

```typescript
// Update row data
grid.rows = newData;

// Wait for grid to be ready
await grid.ready();

// Force layout recalculation
await grid.forceLayout();

// Get current configuration (readonly)
const config = await grid.getConfig();
```

### Row Update API

The Row Update API provides ID-based access to individual rows for reading and updating data. This is especially useful when you need to update rows after external changes (e.g., API responses, WebSocket events) without replacing the entire dataset.

#### Row Identification

The grid automatically determines row IDs using these sources (in order of precedence):

1. `getRowId` function in gridConfig (custom ID resolution)
2. `id` property on the row object
3. `_id` property on the row object

:::note
Rows without any of these will not be accessible via the Row Update API. Calls to `getRow()` or `updateRow()` for such rows will return `undefined` or have no effect.
:::

```typescript
// Configure custom row ID resolution
grid.gridConfig = {
  columns: [...],
  getRowId: (row) => row.employeeId, // Use a custom field as ID
};

// Get a row's ID
const id = grid.getRowId(row);
console.log(id); // "EMP-123"
```

#### Reading Rows

```typescript
// Get a single row by its ID
const employee = grid.getRow('EMP-123');
if (employee) {
  console.log(employee.name);
}

// Returns undefined if the row is not found
const missing = grid.getRow('unknown-id');
console.log(missing); // undefined
```

#### Updating Rows

```typescript
// Update a single row by ID
grid.updateRow('EMP-123', { status: 'active', salary: 75000 });

// Batch update multiple rows
grid.updateRows([
  { id: 'EMP-123', changes: { status: 'active' } },
  { id: 'EMP-456', changes: { department: 'Engineering' } },
]);

// Specify the update source (default: 'api')
// Valid sources: 'user' | 'cascade' | 'api'
grid.updateRow('EMP-123', { status: 'inactive' }, 'api');
grid.updateRows(updates, 'api');
```

#### Listening to Row Updates

The `cell-change` event fires whenever row data is updated via the Row Update API:

```typescript
grid.on('cell-change', ({ rowId, changes, source, row }) => {
  console.log(`Row ${rowId} updated via ${source}:`);
  console.log('Changes:', changes); // { status: 'active' }
  console.log('Full row:', row);    // Complete row object after update
});
```

:::note
The `cell-change` event is distinct from `cell-commit`, which fires during inline editing. Use `cell-change` for programmatic updates via `updateRow()`/`updateRows()`.
:::

### Column Methods

```typescript
// Get all columns with visibility info
const columns = grid.getAllColumns();
// Returns: Array<{ field, header, visible, lockVisible? }>

// Show/hide columns
grid.setColumnVisible('fieldName', false);
grid.toggleColumnVisibility('fieldName');
grid.showAllColumns();

// Check column visibility
const isVisible = grid.isColumnVisible('fieldName');

// Reorder columns
grid.setColumnOrder(['id', 'name', 'email']);
const order = grid.getColumnOrder();
```

### Editing Methods

Bulk-edit lifecycle, change tracking, and active-row controls are provided by the **Editing plugin** and surfaced on the grid instance when the plugin is loaded. See [Editing Plugin → Imperative Bulk-Edit API](/grid/plugins/editing.md#imperative-bulk-edit-api) for the full method list and examples.

### Plugin Methods

| Method                   | Returns                        | Description                                            |
| ------------------------ | ------------------------------ | ------------------------------------------------------ |
| `getPluginByName(name)`  | `Plugin \| undefined`          | Get plugin instance by name — **preferred** (type-safe, no import needed) |
| `getPlugin(PluginClass)` | `P \| undefined`               | Get plugin instance by class (requires import)         |

`getPluginByName` is type-safe for all built-in plugins via the `PluginNameMap` interface — TypeScript automatically returns the correct plugin type (e.g., `SelectionPlugin` for `'selection'`).

```typescript
// Preferred — type-safe, no import needed
const selection = grid.getPluginByName('selection');
selection?.selectAll(); // ✅ SelectionPlugin methods are available

// Alternative — get by class (requires plugin import)
import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';
const sel = grid.getPlugin(SelectionPlugin);

// Check if plugin is registered
if (selection) {
  selection.selectAll();
}
```

### Custom Styles API

The grid uses **light DOM** — standard CSS targeting elements inside `<tbw-grid>` works normally (global stylesheets, `<style>` in `<head>`, external CSS files).

For **programmatic runtime styles**, use `registerStyles()` which injects CSS via `adoptedStyleSheets`:

```typescript
// Inject styles programmatically at runtime
grid.registerStyles('my-id', '.my-class { color: blue; }');

// Remove when no longer needed
grid.unregisterStyles('my-id');

// List currently registered style IDs
const styleIds = grid.getRegisteredStyles();
```

:::caution
Do not place `<style>` elements as **children of `<tbw-grid>`** — the grid calls `replaceChildren()` during renders, which removes child nodes. This only affects `<style>` tags placed *inside* the grid element itself. External stylesheets, `<style>` in `<head>`, and `<link>` tags are completely unaffected.
:::

### Insert & Remove Rows

When you set `rows`, the grid automatically re-applies all active processing — sorting, filtering, grouping — so the data stays consistent. This is the right behavior for data refreshes (e.g., API responses), but **not** for manual row insertion or removal where you want the new row to stay exactly where you placed it.

`insertRow(index, row)` and `removeRow(index)` operate directly on the current view without running the plugin pipeline. The row is also added to / removed from the source data so that the next full pipeline run includes it correctly.

Both methods auto-animate by default (`'insert'` / `'remove'` animation). Pass `false` as the last argument to skip animation. They return `Promise`s that resolve when the animation completes.

```typescript
// Insert a row at visible index 3 (auto-animates)
grid.insertRow(3, newEmployee);

// Insert without animation
grid.insertRow(3, newEmployee, false);
```

```typescript
// Remove with fade-out animation (default) — await to ensure removal
await grid.removeRow(5);

// Remove immediately, no animation
await grid.removeRow(5, false);
```

:::tip
**When to use:** Only for user-initiated row insertion/removal where position matters.
On the next `grid.rows = freshData` assignment, sort and filter re-apply normally.

**When NOT to use:** When receiving fresh data from an API, WebSocket, or any external source. In those cases, just set `grid.rows = newData` and let the grid re-sort and re-filter.
:::

### Row Animation API

All animation methods return `Promise`s that resolve when the animation completes.

```typescript
import type { RowAnimationType } from '@toolbox-web/grid';

// Animate a single row by index (await to know when done)
await grid.animateRow(rowIndex, 'change'); // 'insert' | 'change' | 'remove'

// Animate a row by its ID
await grid.animateRowById('EMP-123', 'insert');

// Animate multiple rows at once
await grid.animateRows([0, 1, 2], 'change');
```

### Loading States

```typescript
// Grid-level loading
grid.loading = true;
grid.loading = false;

// To customise the loading indicator, configure a renderer at config time:
grid.gridConfig = {
  loadingRenderer: (ctx) => {
    const el = document.createElement('div');
    el.textContent = ctx.size === 'large' ? 'Loading…' : '…';
    return el;
  },
};

// Row-level loading (by row ID, not index)
grid.setRowLoading('emp-123', true);
grid.setRowLoading('emp-123', false);

// Cell-level loading (by row ID and field name)
grid.setCellLoading('emp-123', 'email', true);
grid.setCellLoading('emp-123', 'email', false);
```

### Column State Persistence

```typescript
// Get current column state (for saving)
const state = grid.getColumnState();
localStorage.setItem('gridState', JSON.stringify(state));

// Restore column state
const saved = localStorage.getItem('gridState');
if (saved) {
  grid.applyColumnState(JSON.parse(saved));
}

// Reset to initial configuration
grid.resetColumnState();
```

### Shell Methods (Header/Toolbar)

The header bar, toolbar content, and tool panels are owned by the built-in **shell plugin**. Access it via `grid.getPluginByName('shell')` rather than the deprecated `grid.*` element delegates (removed in v3):

```typescript
const shell = grid.getPluginByName('shell');

// Register a tool panel
shell?.registerToolPanel({
  id: 'myPanel',
  title: 'My Panel',
  icon: '⚙️',
  render: (container) => {
    container.innerHTML = '<div>Panel content</div>';
  },
});

// Open/close/toggle the tool panel sidebar
shell?.openToolPanel();
shell?.closeToolPanel();
shell?.toggleToolPanel();

// Open directly on a specific accordion section (one-click navigation)
shell?.openToolPanel('myPanel');

// Toggle specific accordion sections
shell?.toggleToolPanelSection('myPanel');

// Check panel state
const isOpen = shell?.isToolPanelOpen;
const sections = shell?.expandedToolPanelSections;

// Get registered panels
const panels = shell?.getToolPanels();
```

### Header & Toolbar Content

Register custom content in the grid's header bar (above column headers) or toolbar area through the shell plugin:

```typescript
const shell = grid.getPluginByName('shell');

// Register header content (e.g., a search box)
shell?.registerHeaderContent({
  id: 'global-search',
  order: 10,
  render: (container) => {
    const input = document.createElement('input');
    input.type = 'search';
    input.placeholder = 'Search all columns...';
    container.appendChild(input);
  },
});

// Unregister header content
shell?.unregisterHeaderContent('global-search');

// Get all registered header content definitions
const headerContents = shell?.getHeaderContents();

// Register toolbar content (e.g., action buttons)
shell?.registerToolbarContent({
  id: 'export-buttons',
  order: 100,
  render: (container) => {
    const btn = document.createElement('button');
    btn.textContent = 'Export CSV';
    btn.className = 'tbw-toolbar-btn';
    container.appendChild(btn);
  },
});

// Unregister toolbar content
shell?.unregisterToolbarContent('export-buttons');

// Get all registered toolbar content definitions
const toolbarContents = shell?.getToolbarContents();
```

### Row Height

```typescript
// Get the default row height in pixels
// For fixed heights: the configured or CSS-measured row height
// For variable heights: the average/estimated row height
const height = grid.defaultRowHeight;
```

### Focus Management

When building custom editors that render outside the grid DOM (overlays, datepickers, dropdowns appended to `<body>`), use the focus container registry so the grid treats focus inside those elements as "still in the grid".

```typescript
// Register an overlay panel so focus moving into it doesn't close the editor
const panel = document.createElement('div');
document.body.appendChild(panel);
grid.registerExternalFocusContainer(panel);

// When the overlay is torn down, unregister it
grid.unregisterExternalFocusContainer(panel);

// Check whether focus is logically inside the grid (own DOM + external containers)
const hasFocus = grid.containsFocus(); // checks document.activeElement
const nodeInGrid = grid.containsFocus(someNode); // checks specific node
```

:::note
**Angular users:** `BaseOverlayEditor` automatically registers/unregisters its panel — no manual calls needed.
:::

### Focus & Navigation API

Programmatic cell focus and scroll-to-row:

```typescript
// Focus a cell by column index or field name
grid.focusCell(0, 2);         // row 0, column index 2
grid.focusCell(5, 'email');   // row 5, field 'email'

// Read the currently focused cell
const cell = grid.focusedCell;
if (cell) {
  console.log(`Row ${cell.rowIndex}, field "${cell.field}"`);
}

// Scroll a row into view (no-op if already visible)
grid.scrollToRow(42);

// Center the row with smooth scrolling
grid.scrollToRow(42, { align: 'center', behavior: 'smooth' });

// Scroll by row ID (requires getRowId or id/_id property)
grid.scrollToRowById('emp-42', { align: 'center' });
```

**`ScrollToRowOptions`:**

| Option     | Type                                          | Default     | Description                      |
| ---------- | --------------------------------------------- | ----------- | -------------------------------- |
| `align`    | `'start' \| 'center' \| 'end' \| 'nearest'`  | `'nearest'` | Where to position the row        |
| `behavior` | `'instant' \| 'smooth'`                       | `'instant'` | Scroll animation                 |

## Events

The grid dispatches standard `CustomEvent`s that bubble up the DOM. All events use `bubbles: true` and `composed: true`.

```ts
// CoreEventsDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

  const container = document.getElementById('demo-core-events')?.closest('.grid-demo');
  if (container) {
    const grid = queryGrid('tbw-grid', container)!;

    const logEl = container.querySelector<HTMLElement>('[data-event-log]')!;
    let count = 0;

    grid.columns = [
      { field: 'id', header: 'ID', width: 60 },
      { field: 'name', header: 'Name', width: 150 },
      { field: 'role', header: 'Role', width: 130 },
      { field: 'score', header: 'Score', type: 'number', width: 80 },
    ];
    grid.sortable = true;
    grid.resizable = true;

    grid.rows = [
      { id: 1, name: 'Alice', role: 'Engineer', score: 92 },
      { id: 2, name: 'Bob', role: 'Designer', score: 78 },
      { id: 3, name: 'Carol', role: 'Manager', score: 85 },
      { id: 4, name: 'Dan', role: 'Engineer', score: 64 },
      { id: 5, name: 'Eve', role: 'Designer', score: 91 },
    ];

    function logEvent(name: string, detail: unknown) {
      count++;
      const entry = document.createElement('div');
      entry.style.cssText = 'padding:2px 0;border-bottom:1px solid var(--sl-color-gray-5);';
      const summary = typeof detail === 'object' && detail
        ? JSON.stringify(detail).slice(0, 120)
        : String(detail);
      entry.innerHTML = `<span style="color:var(--sl-color-accent)">${count}.</span> <strong>${name}</strong> — ${summary}`;
      logEl.appendChild(entry);
      logEl.scrollTop = logEl.scrollHeight;
    }

    const events = ['cell-click', 'row-click', 'cell-activate', 'sort-change', 'column-resize', 'column-state-change', 'data-change'];
    for (const name of events) {
      grid.on(name, (detail: unknown) => logEvent(name, detail));
    }

    container.querySelector('[data-clear-log]')!.addEventListener('click', () => {
      logEl.innerHTML = '';
      count = 0;
    });
  }
```

### Listening to Events

For framework-specific patterns (vanilla TypeScript, React, Vue, Angular) and the camelCase vs kebab-case binding rules, see [Common Patterns → Event Handling Recipes](/grid/guides/common-patterns.md#listening-to-events-across-frameworks).

### Cancelable Events

Five events support `preventDefault()` to reject the action:

| Event | Plugin | What Canceling Does |
|-------|--------|-------------------|
| `cell-activate` | Core | Suppresses the default activation — prevents plugins (e.g. inline editing) from acting on the click/keypress |
| `cell-commit` | Editing | Reverts the cell to its previous value |
| `row-commit` | Editing | Reverts the entire row to pre-edit state |
| `column-move` | Reorder | Rejects the column drag-and-drop |
| `row-move` | Row Reorder | Rejects the row drag/keyboard move |

`cell-activate` fires **first**, before any plugin handles the interaction, and for **both** pointer clicks and keyboard activation (Enter) — its `detail.trigger` is `'pointer'` or `'keyboard'`. Because it covers the keyboard path and is cancelable, prefer it over `cell-click` (pointer-only) for click-to-open / activate-to-edit patterns that must stay keyboard-accessible.

### Scroll & Render Recipes

The `tbw-scroll` event fires (rAF-batched) on every viewport scroll; the `render` event fires once per render flush after all plugin `afterRender` hooks complete. Cookbook patterns — infinite scroll, sticky progress indicators, lazy cell hydration, post-`addRow` focus, phase-gated render handlers — live in [Common Patterns → Event Handling Recipes](/grid/guides/common-patterns.md#scroll-driven-patterns-tbw-scroll).

For the typed event payloads, see [`DataGridEventMap`](/grid/api/core/interfaces/datagrideventmap.md).

### Event Reference

The [`DataGridEventMap`](/grid/api/core/interfaces/datagrideventmap.md) is the complete, auto-generated reference for every event the grid dispatches — core events and plugin events alike. It includes detail payload types, descriptions, and code examples, grouped by plugin.

- [DataGridEventMap Reference](/grid/api/core/interfaces/datagrideventmap.md): Full list of every event, grouped by plugin, with payload types and code examples.

:::note[Multi-Sort overrides `sort-change`]
When `MultiSortPlugin` is active, the `sort-change` event payload changes from `SortChangeDetail` (single `{ field, direction }`) to `{ sortModel: SortModel[] }` (array of sort columns). This override cannot be expressed in `DataGridEventMap` because TypeScript declaration merging doesn't allow changing a property type. Import `SortModel` from `@toolbox-web/grid/plugins/multi-sort`.
:::

## CSS Custom Properties

The grid exposes ~80 CSS custom properties for theming. See the [Theming guide](/grid/guides/theming.md#css-variable-reference) for the complete, categorised list and the [`GridIcons` interface](/grid/api/core/interfaces/gridicons.md) for the icon variables.

## Configuration Patterns

The patterns that show how to *use* the configuration API live with their respective guides — this section is just a directory:

| Pattern | Where it lives |
|---|---|
| Dynamic `rowClass` / `cellClass` | [Core → Row Styling](/grid/core.md#row-styling) & [Cell Styling](/grid/core.md#cell-styling) |
| Type-level defaults (formatters, renderers, editors) | [Core → Type-Level Defaults](/grid/core.md#type-level-defaults) |
| Row animation (expand/collapse, reorder, insert/remove) | [Core → Row Animation](/grid/core.md#row-animation) and the [`AnimationConfig` interface](/grid/api/core/interfaces/animationconfig.md) |
| Shell layout (header, toolbar, tool panels) | [Shell plugin](/grid/plugins/shell.md) and the [`ShellConfig` interface](/grid/plugins/shell/interfaces/shellconfig.md) |
| Icon customization (CSS + JS paths) | [Theming → Icon Customization](/grid/guides/theming.md#icon-customization) and the [`GridIcons` interface](/grid/api/core/interfaces/gridicons.md) |

## Accessibility & Keyboard

The grid implements the [W3C WAI-ARIA Grid Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) out of the box — ARIA roles (`grid` / `row` / `gridcell` / `columnheader`), `aria-rowindex` / `aria-colindex` / `aria-rowcount` / `aria-colcount`, `aria-sort`, `aria-selected`, `aria-readonly`, and `aria-checked` are applied automatically.

Configure accessible naming via `gridAriaLabel` / `gridAriaDescribedBy` on [`GridConfig`](/grid/api/core/interfaces/gridconfig.md). Customise screen-reader announcements via [`A11yConfig`](/grid/api/core/interfaces/a11yconfig.md).

For the full keyboard shortcut matrix, ARIA reference, screen-reader guidance, focus management, and high-contrast support, see the [Accessibility guide](/grid/guides/accessibility.md).

## Browser Support

Modern evergreen browsers — Chrome/Edge 79+, Firefox 63+, Safari 13.1+. No polyfills required. See the [Production Checklist](/grid/guides/production-checklist.md) for deployment guidance.

## Related Documentation

- [Core Features](/grid/core.md) — Detailed guide on columns, renderers, and formatters
- [Shell plugin](/grid/plugins/shell.md) — Header bar, toolbar, and tool-panel sidebar
- [Theming](/grid/guides/theming.md) — Complete CSS custom property reference and theme customization
- [Getting Started](/grid/getting-started.md) — Installation and quick start guide
- [Demos](/grid/demos.md) — Full-featured demo applications
- [Angular Adapter](/grid/angular/getting-started.md) — `@toolbox-web/grid-angular`
- [React Adapter](/grid/react/getting-started.md) — `@toolbox-web/grid-react`
- [Vue Adapter](/grid/vue/getting-started.md) — `@toolbox-web/grid-vue`

---

# Error & Warning Reference

> Complete reference for all diagnostic codes emitted by @toolbox-web/grid. Each code links to an explanation and resolution steps.

Every warning and error in `@toolbox-web/grid` includes a **diagnostic code** (e.g. `TBW001`) and a link back to this page. Find your code below for an explanation and fix.

---

## Configuration Validation

<div id="tbw001" />

### TBW001 — Missing Plugin (Column Property)

A column uses a property (like `editable`, `editor`, `pinned`, or `group`) that requires a plugin, but that plugin isn't loaded.

**Fix:** Import and add the required plugin:

```ts
// For editing
import '@toolbox-web/grid/features/editing';

grid.gridConfig = {
  features: { editing: true },
  columns: [{ field: 'name', editable: true }],
};
```

Or with the plugin API directly:

```ts
import { EditingPlugin } from '@toolbox-web/grid/plugins/editing';

grid.gridConfig = {
  plugins: [new EditingPlugin()],
  columns: [{ field: 'name', editable: true }],
};
```

  - [Editing Plugin](/grid/plugins/editing.md)
  - [Pinned Columns Plugin](/grid/plugins/pinned-columns.md)
  - [Grouping Columns Plugin](/grid/plugins/grouping-columns.md)
  - [Getting Started](/grid/getting-started.md)

<div id="tbw002" />

### TBW002 — Missing Plugin (Config Property)

A grid config property (like `columnGroups`) requires a plugin that isn't loaded.

**Fix:** Same as TBW001 — import the required feature or plugin.

- [Plugins Overview](/grid/plugins.md)

<div id="tbw003" />

### TBW003 — Config Rule Error

A plugin's configuration rule detected an invalid combination. The error message describes the specific rule that was violated.

**Fix:** Check the error message for the specific plugin and configuration that triggered the rule. Adjust the plugin config to avoid the invalid combination.

<div id="tbw004" />

### TBW004 — Config Rule Warning

A plugin detected a potentially problematic configuration. This is a development-only warning — the grid will still work, but behavior may be unexpected.

**Fix:** Read the warning message and adjust your config accordingly.

- [Plugins Overview](/grid/plugins.md)

---

## Plugin Lifecycle

<div id="tbw020" />

### TBW020 — Missing Plugin Dependency

A plugin requires another plugin to be loaded first. For example, `UndoRedoPlugin` requires `EditingPlugin`.

**Fix:** Add the dependency plugin **before** the dependent one:

```ts
import '@toolbox-web/grid/features/editing';
import '@toolbox-web/grid/features/undoRedo';

grid.gridConfig = {
  features: {
    editing: true,
    undoRedo: true,
  },
};
```

  - [Plugins Overview](/grid/plugins.md)
  - [Custom Plugins Guide](/grid/plugin-development/custom-plugins.md)

<div id="tbw021" />

### TBW021 — Optional Dependency Missing

A plugin has an optional dependency that isn't loaded. The plugin will still work, but some features may be unavailable. This message is logged at the `debug` level and only visible when the browser DevTools "Verbose" log level is enabled.

**Fix:** If you need the full feature set, add the optional dependency. Otherwise, this message can be safely ignored.

<div id="tbw022" />

### TBW022 — Incompatible Plugins

Two plugins that are known to conflict are both loaded. Development-only warning.

**Fix:** Remove one of the conflicting plugins. The warning message names both plugins and explains the conflict.

:::note[PinnedColumnsPlugin + GroupingColumnsPlugin]
As of the latest release, `PinnedColumnsPlugin` and `GroupingColumnsPlugin` **are compatible**. Pinning a grouped column temporarily moves it to the grid edge, causing the column group to fragment. Unpinning restores the column to its original position within the group. No action is needed.
:::

<div id="tbw023" />

### TBW023 — Deprecated Hook

A plugin uses a deprecated API that will be removed in a future major version.

**Fix:** Migrate to the recommended replacement described in the warning message.

<div id="tbw024" />

### TBW024 — Plugin Event Handler Error

An error was thrown inside a plugin event handler. This doesn't crash the grid — the error is caught and logged — but it indicates a bug in plugin code.

**Fix:** Check the stack trace to find and fix the error in the plugin's event handler.

- [Custom Plugins Guide](/grid/plugin-development/custom-plugins.md)

<div id="tbw025" />

### TBW025 — Plugin Alias Config Conflict

Two plugin instances resolve to the same canonical name (for example, both `RowReorderPlugin` and `RowDragDropPlugin` are passed in `plugins`), and they supply conflicting values for the same configuration key. The grid cannot decide which one wins.

**Fix:** Pass the option on a single instance, or remove the duplicate plugin. If you only need the legacy API surface, keep `RowReorderPlugin`; if you need cross-grid drag, keep `RowDragDropPlugin`.

```ts
// ❌ Conflict: both instances configure `animation`
plugins: [
  new RowReorderPlugin({ animation: 'fade' }),
  new RowDragDropPlugin({ animation: 'flip' }),
]

// ✅ Configure on one instance only
plugins: [
  new RowDragDropPlugin({ animation: 'flip' }),
]
```

---

## Feature Registry

<div id="tbw030" />

### TBW030 — Feature Re-registered

A feature was registered more than once. The previous registration was overwritten. This typically happens when two different versions of the same feature module are loaded.

**Fix:** Check your bundle for duplicate imports. Each feature should be imported exactly once.

<div id="tbw031" />

### TBW031 — Feature Not Imported

A feature is configured in `gridConfig.features` but its module was never imported. Features require a side-effect import to register themselves.

**Fix:** Add the import shown in the warning:

```ts
import '@toolbox-web/grid/features/selection';

grid.gridConfig = {
  features: { selection: 'row' },
};
```

Framework adapters handle this automatically — if you're using Angular, React, or Vue adapters, import from the adapter package instead.

- [Getting Started](/grid/getting-started.md)

<div id="tbw032" />

### TBW032 — Feature Missing Dependency

A feature requires another feature to be enabled. For example, `clipboard` requires `selection`.

**Fix:** Add the required feature to your config:

```ts
grid.gridConfig = {
  features: {
    selection: 'range',
    clipboard: true,
  },
};
```

- [Getting Started](/grid/getting-started.md)

---

## Row Operations

<div id="tbw040" />

### TBW040 — Missing Row ID

The grid needs to identify a row but couldn't determine its ID. This happens when:

- Rows don't have an `id` or `_id` property
- No `getRowId` function is configured

**Fix:** Either add an `id` field to your data, or configure `getRowId`:

```ts
grid.gridConfig = {
  getRowId: (row) => row.employeeNumber,
};
```

- [Core Features](/grid/core.md)

<div id="tbw041" />

### TBW041 — Row Not Found

A row update or delete operation referenced a row ID that doesn't exist in the grid.

**Fix:** Verify the row ID is correct and the row hasn't been removed. Use `grid.getRow(id)` to check if a row exists before updating.

- [Core Features](/grid/core.md)

---

## Column Operations

<div id="tbw050" />

### TBW050 — Invalid Column Width

A column's `width` value is not a valid CSS grid track size. Development-only warning.

**Fix:** Use a number (interpreted as pixels) or a valid CSS string:

```ts
{ field: 'name', width: 200 }       // 200px
{ field: 'name', width: '30%' }     // 30%
{ field: 'name', width: '2fr' }     // 2 fractional units
{ field: 'name', width: 'auto' }    // auto
```

- [Core Features — Columns](/grid/core.md)

---

## Rendering Callbacks

<div id="tbw060" />

### TBW060 — rowClass Callback Error

The `rowClass` function threw an error during rendering. The row will render without dynamic classes.

**Fix:** Check your `rowClass` function for null/undefined access or type errors.

<div id="tbw061" />

### TBW061 — cellClass Callback Error

A column's `cellClass` function threw an error. The cell will render without dynamic classes.

**Fix:** Check the `cellClass` function on the column named in the warning.

<div id="tbw062" />

### TBW062 — Format Error

A column's `format` function threw an error. The raw value will be displayed instead.

**Fix:** Check the `format` function on the named column. Ensure it handles null/undefined values gracefully.

<div id="tbw063" />

### TBW063 — External View Mount Error

An `externalView.mount()` callback threw during cell rendering.

**Fix:** Debug the `mount` function in your external view configuration for the named column.

<div id="tbw064" />

### TBW064 — External View Dispatch Error

The `mount-external-view` event dispatch failed for a cell.

**Fix:** Check event listeners attached to the `mount-external-view` event on the grid.

- [Core Features — Rendering](/grid/core.md)

---

## Shell

<div id="tbw070" />

### TBW070 — Tool Panel Missing Attributes

A `<tbw-grid-tool-panel>` light DOM element is missing required `id` or `title` attributes.

**Fix:** Add both attributes:

```html
<tbw-grid-tool-panel id="my-panel" title="My Panel">
  Panel content here
</tbw-grid-tool-panel>
```

<div id="tbw071" />

### TBW071 — No Tool Panels

`openToolPanel()` was called but no tool panels are registered.

**Fix:** Register at least one tool panel before attempting to open the panel.

<div id="tbw072" />

### TBW072 — Tool Panel Not Found

`toggleToolPanelSection()` was called with a section ID that doesn't match any registered panel.

**Fix:** Verify the section ID matches a registered tool panel's `id`.

<div id="tbw073" />

### TBW073 — Duplicate Tool Panel

A tool panel with the same `id` was registered twice. The duplicate was ignored.

**Fix:** Ensure each tool panel has a unique `id`.

<div id="tbw074" />

### TBW074 — Duplicate Header Content

Header content with the same `id` was registered twice.

**Fix:** Use unique IDs for header content registrations.

<div id="tbw075" />

### TBW075 — Duplicate Toolbar Content

Toolbar content with the same `id` was registered twice.

**Fix:** Use unique IDs for toolbar content registrations.

- [Architecture — Shell](/grid/architecture.md)

---

## Editing

<div id="tbw080" />

### TBW080 — Editor Mount Error

An external editor's `mount()` function threw during edit activation.

**Fix:** Debug the editor's `mount` function. Ensure it handles the editor context correctly.

- [Editing Plugin](/grid/plugins/editing.md)

---

## Print

<div id="tbw090" />

### TBW090 — Print In Progress

`print()` was called while a print operation is already running.

**Fix:** Wait for the current print to complete before starting another. Listen for the `print-complete` event.

<div id="tbw091" />

### TBW091 — Grid Not Available

`print()` was called but the grid element is not available (likely disconnected from the DOM).

**Fix:** Ensure the grid is mounted before calling `print()`.

<div id="tbw092" />

### TBW092 — Print Failed

The print operation encountered an error. The `print-complete` event will fire with `success: false`.

**Fix:** Check the error details in the console. Common causes include the grid being too large or the user canceling the print dialog.

<div id="tbw093" />

### TBW093 — Duplicate Grid ID (Print)

Multiple elements on the page share the same `id` as the grid. This interferes with print isolation.

**Fix:** Assign a unique `id` to each grid element on the page.

- [Print Plugin](/grid/plugins/print.md)

---

## Clipboard

<div id="tbw100" />

### TBW100 — Clipboard API Failed

The browser's `navigator.clipboard.writeText()` failed. The grid falls back to `document.execCommand('copy')`.

**Fix:** This usually happens when the page isn't focused or lacks the clipboard permission. The fallback typically succeeds, so this warning is informational.

- [Clipboard Plugin](/grid/plugins/clipboard.md)

---

## Plugin-Specific

<div id="tbw110" />

### TBW110 — Missing Breakpoint (Responsive)

`ResponsivePlugin` is loaded but no `breakpoint` is configured. The plugin will not activate.

**Fix:** Set a breakpoint based on your container width:

```ts
grid.gridConfig = {
  features: {
    responsive: { breakpoint: 600 },
  },
};
```

- [Responsive Plugin](/grid/plugins/responsive.md)

<div id="tbw111" />

### TBW111 — Transaction In Progress (Undo/Redo)

`beginTransaction()` was called while a transaction is already open.

**Fix:** Call `endTransaction()` before starting a new transaction.

<div id="tbw112" />

### TBW112 — No Transaction (Undo/Redo)

`endTransaction()` was called without a matching `beginTransaction()`.

**Fix:** Ensure every `endTransaction()` has a preceding `beginTransaction()`.

- [Undo/Redo Plugin](/grid/plugins/undo-redo.md)

<div id="tbw113" />

### TBW113 — Column Group Missing ID

A `ColumnGroupDefinition` has neither `id` nor `header`. The grid cannot generate an identifier.

**Fix:** Add either an `id` or `header` to every column group definition:

```ts
columnGroups: [
  { id: 'personal', header: 'Personal Info', children: ['name', 'age'] },
]
```

<div id="tbw114" />

### TBW114 — Conflicting Column Groups

`columnGroups` are defined in both `gridConfig` and the `groupingColumns` feature config. The feature config takes precedence.

**Fix:** Define column groups in only one place — preferably in the feature config.

- [Grouping Columns Plugin](/grid/plugins/grouping-columns.md)

---

## Style Injection

<div id="tbw120" />

### TBW120 — Style Extraction Failed

The grid couldn't extract its CSS from `document.styleSheets` due to a CORS or access error.

**Fix:** Ensure the grid's CSS file is served from the same origin, or add CORS headers to the stylesheet response.

<div id="tbw121" />

### TBW121 — Stylesheet Not Found

The grid's CSS was not found in `document.styleSheets`. The grid will render without styling.

**Fix:** Ensure you're importing the grid's CSS. For most setups:

```ts
import '@toolbox-web/grid/style.css';
```

Or link it in your HTML:

```html
<link rel="stylesheet" href="node_modules/@toolbox-web/grid/style.css" />
```

  - [Getting Started — Installation](/grid/getting-started.md)
  - [Theming Guide](/grid/guides/theming.md)

---

## Attribute Parsing

<div id="tbw130" />

### TBW130 — Invalid Attribute JSON

An HTML attribute (`rows`, `columns`, or `grid-config`) contains invalid JSON.

**Fix:** Verify the attribute value is valid JSON. For complex config, use JavaScript properties instead of HTML attributes:

```ts
import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.gridConfig = { columns: [...], ... };
```

- [Getting Started](/grid/getting-started.md)

---

## DataSource

<div id="tbw140" />

### TBW140 — DataSource Fetch Error

The `getRows()` call on the data source threw an error or returned a rejected promise.

**Fix:** Check your data source implementation for network errors, malformed responses, or server-side failures. The error detail is included in the diagnostic message and in the `datasource:error` event.

<div id="tbw141" />

### TBW141 — DataSource Child Fetch Error

The `getChildRows()` call on the data source threw an error or returned a rejected promise.

**Fix:** Check your `getChildRows()` implementation. The error and parent context are included in the diagnostic message.

<div id="tbw142" />

### TBW142 — No Child Row Handler

A plugin requested child rows via `datasource:fetch-children`, but the active data source does not implement `getChildRows()`.

**Fix:** Add a `getChildRows()` method to your `ServerSideDataSource` if you are using Tree, GroupingRows, or MasterDetail plugins with server-side data.

<div id="tbw143" />

### TBW143 — DataSource Request Throttled

A data fetch request was skipped because the maximum number of concurrent requests was already in-flight.

**Info:** This is a debug-level diagnostic. The request will be retried automatically on the next scroll or render cycle.

---

# Compared to Other Grids

> How @toolbox-web/grid stacks up against AG Grid, Tabulator, and SlickGrid — features, bundle size, and a live performance benchmark you can run in your browser.

This page compares `@toolbox-web/grid` against three widely-used JavaScript data grids: **AG Grid**, **Tabulator**, and **SlickGrid**. The goal is an honest side-by-side on features, bundle size, and — below — measured performance in your own browser.

## Migrating to Toolbox Grid

Most concepts in the other grids map cleanly to Toolbox Grid. Pick the section for your current grid below.

### From AG Grid

| AG Grid | Toolbox Grid |
|---------|-------------|
| `columnDefs` | `columns` or `gridConfig.columns` |
| `rowData` | `rows` |
| `defaultColDef` | Per-type defaults via `typeDefaults` (keyed by `column.type`) |
| `getRowId` | `getRowId: (row) => string` (same shape) |
| `onCellValueChanged` | `cell-commit` event |
| `onSelectionChanged` | `selection-change` event |
| `serverSideRowModel` | `ServerSidePlugin` |
| `rowGrouping` | `GroupingRowsPlugin` |
| `masterDetail` | `MasterDetailPlugin` |

Side-by-side AG Grid → Toolbox Grid for the same minimal setup: data, columns, and row selection.

#### Angular

```typescript
// AG Grid
import { Component } from '@angular/core';
import { AgGridAngular } from 'ag-grid-angular';

@Component({
  imports: [AgGridAngular],
  template: `
    <ag-grid-angular
      [rowData]="rows"
      [columnDefs]="columns"
      rowSelection="multiple">
    </ag-grid-angular>
  `,
})
export class MyGridComponent {}
```

```typescript
// Toolbox Grid
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';

@Component({
  imports: [Grid, GridSelectionDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [selection]="'row'">
    </tbw-grid>
  `,
})
export class MyGridComponent {}
```

### From Tabulator

| Tabulator | Toolbox Grid |
|-----------|--------------|
| `new Tabulator(el, options)` | `<tbw-grid>` element + `grid.gridConfig = { ... }` |
| `columns: [{ field, title, ... }]` | `columns: [{ field, header, ... }]` (rename `title` → `header`) |
| `data` option / `setData(rows)` | `grid.rows = rows` |
| `index: 'id'` | `getRowId: (row) => String(row.id)` |
| `layout: 'fitColumns'` / `'fitDataFill'` | `fitMode: 'auto'` / `'fixed'` |
| `setSort([{ column, dir }])` | `grid.sort(field, 'asc' \| 'desc')` |
| `setFilter(field, type, value)` | `FilteringPlugin` + `filterPlugin.setFilterModel([...])` |
| `cellEdited` callback | `cell-commit` event |
| `rowSelected` callback | `selection-change` event |
| `dataTree: true` | `TreeDataPlugin` |
| `pagination: 'local'` | `PaginationPlugin` |

```html
<!-- Tabulator -->
<div id="myGrid" style="height: 400px;"></div>

<script type="module">
  import { Tabulator } from 'tabulator-tables';

  new Tabulator('#myGrid', {
    data: rows,
    columns: [
      { title: 'Name', field: 'name', headerSort: true },
      { title: 'Email', field: 'email' },
    ],
    selectableRows: true,
  });
</script>
```

```html
<!-- Toolbox Grid -->
<tbw-grid style="height: 400px;"></tbw-grid>

<script type="module">
  import '@toolbox-web/grid';
  import '@toolbox-web/grid/features/selection';
  import { queryGrid } from '@toolbox-web/grid';

  const grid = queryGrid('tbw-grid');
  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name', sortable: true },
      { field: 'email', header: 'Email' },
    ],
    features: { selection: 'row' },
  };
  grid.rows = rows;
</script>
```

### From SlickGrid

SlickGrid's API is lower-level than the others — most behavior is composed from `Slick.Grid` + `Slick.Data.DataView` + plugin instances. Toolbox Grid bundles the equivalents into config and built-in plugins.

| SlickGrid | Toolbox Grid |
|-----------|--------------|
| `new Slick.Grid(el, dataView, columns, options)` | `<tbw-grid>` + `grid.gridConfig = { columns, ... }` |
| `Slick.Data.DataView` | Built into the grid; pass plain arrays to `grid.rows` |
| `columns: [{ id, name, field }]` | `columns: [{ field, header }]` (drop separate `id`; `field` is the key) |
| `dataView.setItems(rows, 'id')` | `grid.rows = rows` + `getRowId: (row) => String(row.id)` |
| `dataView.sort(comparer, asc)` | `grid.sort(field, 'asc' \| 'desc')` |
| `dataView.setFilter(fn)` | `FilteringPlugin` (declarative filter model) |
| `Slick.Plugins.RowSelectionModel` | `features: { selection: 'row' }` |
| `Slick.CheckboxSelectColumn` | `features: { selection: 'checkbox' }` |
| `Slick.CellRangeSelector` + `CellSelectionModel` | `RangeSelectionPlugin` |
| `onCellChange` | `cell-commit` event |
| `onSelectedRowsChanged` | `selection-change` event |
| Manual jQuery resize handler | Built-in column resize feature |

```html
<!-- SlickGrid -->
<div id="myGrid" style="height: 400px;"></div>

<script type="module">
  // SlickGrid 6pac fork v2.4.x — global Slick namespace
  const dataView = new Slick.Data.DataView();
  dataView.setItems(rows, 'id');

  const grid = new Slick.Grid('#myGrid', dataView, [
    { id: 'name', name: 'Name', field: 'name', sortable: true },
    { id: 'email', name: 'Email', field: 'email' },
  ], { enableCellNavigation: true });

  grid.setSelectionModel(new Slick.RowSelectionModel());
</script>
```

```html
<!-- Toolbox Grid -->
<tbw-grid style="height: 400px;"></tbw-grid>

<script type="module">
  import '@toolbox-web/grid';
  import '@toolbox-web/grid/features/selection';
  import { queryGrid } from '@toolbox-web/grid';

  const grid = queryGrid('tbw-grid');
  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name', sortable: true },
      { field: 'email', header: 'Email' },
    ],
    getRowId: (row) => String(row.id),
    features: { selection: 'row' },
  };
  grid.rows = rows;
</script>
```

### From TanStack Table

TanStack Table is a headless utility — you bring your own markup, virtualization, and DOM. Toolbox Grid is a rendering web component, so most of TanStack's row-model plumbing (`getSortedRowModel`, `getFilteredRowModel`, `useVirtualizer`) becomes built-in behavior or a one-line feature import.

| TanStack Table | Toolbox Grid |
|----------------|--------------|
| `useReactTable(options)` | Not needed — render `<DataGrid>` directly |
| `columnHelper.accessor('field', …)` | Column config `{ field }` (or `valueAccessor` for computed values) |
| `columnHelper.display({ cell })` | Column with a `renderer` |
| `cell: (info) => …` / `flexRender` | `renderer: (ctx) => …` (returns JSX in React) |
| `getSortedRowModel()` | `sortable: true` (built-in) |
| `getFilteredRowModel()` | `features: { filtering: true }` (`FilteringPlugin`) |
| `getGroupedRowModel()` | `features: { groupingRows: { groupOn } }` |
| `getExpandedRowModel()` | `features: { tree: { childrenField } }` or `masterDetail` |
| `@tanstack/react-virtual` / `useVirtualizer()` | Built-in row virtualization — no setup |
| `state.sorting` / `onSortingChange` | `sort-change` event |
| `state.rowSelection` / `onRowSelectionChange` | `features: { selection: 'row' }` + `selection-change` event |

```tsx
// TanStack Table (React)
import {
  useReactTable,
  getCoreRowModel,
  getSortedRowModel,
  flexRender,
} from '@tanstack/react-table';

const table = useReactTable({
  data: rows,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
});

// …then hand-render <table>, <thead>, <tbody> with flexRender(...)
```

```tsx
// Toolbox Grid (React)
import '@toolbox-web/grid-react/features/selection';
import { DataGrid, type GridConfig } from '@toolbox-web/grid-react';

const gridConfig: GridConfig<Row> = {
  columns, // { field, header, sortable, renderer? }
  features: { selection: 'row' },
};

<DataGrid rows={rows} gridConfig={gridConfig} style={{ height: 400 }} />;
```

### From ngx-datatable

ngx-datatable is Angular-only. Toolbox Grid's Angular adapter mirrors its declarative, template-driven style: keep `[rows]` as-is, rename column inputs, and swap `<ng-template>` cell templates for the `*tbwRenderer` structural directive.

| ngx-datatable | Toolbox Grid |
|---------------|--------------|
| `<ngx-datatable>` | `<tbw-grid>` with the `Grid` directive |
| `[rows]` | `[rows]` (same!) |
| `[columns]="[{ prop, name }]"` | `[columns]="[{ field, header }]"` |
| `<ngx-datatable-column prop="x">` | `<tbw-grid-column field="x">` |
| `[name]` | `header` |
| `<ng-template ngx-datatable-cell-template let-value="value">` | `*tbwRenderer="let value"` |
| `[sortable]` on column | `sortable: true` on column |
| `(activate)` | `(cellActivate)` / `cell-activate` event |
| `[selected]` / `(select)` + `SelectionType` | `[selection]="'row'"` + `selection-change` event |
| `[scrollbarV]="true"` (virtual scroll) | Built-in row virtualization — no input needed |
| `[groupRowsBy]` | `GroupingRowsPlugin` (`features: { groupingRows }`) |
| `[treeFromRelation]` / `[treeToRelation]` | `TreePlugin` (`features: { tree }`) |

```html
<!-- ngx-datatable -->
<ngx-datatable
  [rows]="rows"
  [columns]="[{ prop: 'name', name: 'Name' }, { prop: 'email', name: 'Email' }]"
  [selectionType]="'single'"
  (select)="onSelect($event)">
</ngx-datatable>
```

```html
<!-- Toolbox Grid (Angular adapter) -->
<!-- imports: [Grid, GridSelectionDirective] -->
<tbw-grid
  style="height: 400px;"
  [rows]="rows"
  [columns]="[{ field: 'name', header: 'Name' }, { field: 'email', header: 'Email' }]"
  [selection]="'row'"
  (selectionChange)="onSelect($event)">
</tbw-grid>
```

## Get Started

```bash
npm install @toolbox-web/grid
```

```typescript
import '@toolbox-web/grid';

const grid = document.createElement('tbw-grid');
grid.columns = [
  { field: 'name', header: 'Name', sortable: true },
  { field: 'email', header: 'Email' },
];
grid.rows = [
  { name: 'Alice', email: 'alice@example.com' },
  { name: 'Bob', email: 'bob@example.com' },
];
document.body.appendChild(grid);
```

**Ready to switch?** Check out our [Getting Started guide](/grid/getting-started.md) or [live demos](/grid/demos.md).

## See Also

- [Getting Started](/grid/getting-started.md) — Install and set up your first grid in minutes
- [Demos](/grid/demos.md) — Full-featured employee management demo
- [Plugins Overview](/grid/plugins.md) — Complete plugin catalog with feature comparison

---

# Plugins Overview

> Overview of all @toolbox-web/grid plugins — editing, selection, filtering, grouping, export, and more. Tree-shakeable, individually importable.

The `@toolbox-web/grid` plugin architecture allows you to extend the grid with powerful features while keeping the core bundle lightweight. Plugins are tree-shakeable — only import what you need.

:::tip[Features or Plugins? They do the same thing.]
**Features** and **plugins** are two APIs for enabling the same capabilities. The end result is identical — features are simply a simpler, declarative wrapper around plugins.

- **Features** (recommended) — Declare _what_ you want: `features: { selection: 'row' }`. Dependencies are auto-resolved, ordering is handled for you.
- **Plugins** (advanced) — Instantiate classes yourself: `plugins: [new SelectionPlugin({ mode: 'row' })]`. Useful when building custom plugins or extending `BaseGridPlugin`.

**If you're getting started, use features.** You can always switch to the plugin API later if you need more control — they're fully interchangeable.
:::

:::note[Angular: pair feature inputs with the per-feature directive]
The Angular tabs in plugin docs often show the shorthand `[selection]`, `[filtering]`, `[editing]`, etc. on `<tbw-grid>`. In **v1.4+** the recommended way to use those bindings is to import the matching per-feature directive (e.g. [`GridSelectionDirective`](/grid/angular/api/directives/gridselectiondirective.md) from `@toolbox-web/grid-angular/features/selection`) alongside `Grid` in the component's `imports`. The same bindings on the central `Grid` directive are still accepted for v1.x backward compatibility but are `@deprecated` and will be removed in v2.0. Apps that configure plugins through `[gridConfig]="{ features: { … } }"` are unaffected — see the [Angular getting-started guide](/grid/angular/getting-started.md#three-ways-to-configure-features) for the full breakdown.
:::

## Available Plugins

### Editing & Data Entry

| Plugin | Description |
| ------ | ----------- |
| [Editing](/grid/plugins/editing.md) | Inline cell editing with built-in editors |
| [Undo/Redo](/grid/plugins/undo-redo.md) | Undo/redo for cell edits with history stack |

:::note
Editing is opt-in. To enable `editable` and `editor` column properties, you must enable the editing feature (`features: { editing: true }`) or register the `EditingPlugin` directly. This keeps the core bundle lightweight and provides runtime validation to catch misconfigurations early.
:::

### Selection & Interaction

| Plugin | Description |
| ------ | ----------- |
| [Selection](/grid/plugins/selection.md) | Cell, row, and range selection with keyboard support |
| [Clipboard](/grid/plugins/clipboard.md) | Copy/paste with Ctrl+C/V |
| [Context Menu](/grid/plugins/context-menu.md) | Right-click context menus with submenus |
| [Reorder](/grid/plugins/reorder-columns.md) | Drag-and-drop column reordering |
| [Row Reorder](/grid/plugins/reorder-rows.md) | Drag-and-drop row reordering with keyboard support |

### Filtering & Sorting

| Plugin | Description |
| ------ | ----------- |
| [Filtering](/grid/plugins/filtering.md) | Column header filters with search and dropdown |
| [Multi-Sort](/grid/plugins/multi-sort.md) | Sort by multiple columns with priority indicators |

### Grouping & Hierarchy

| Plugin | Description |
| ------ | ----------- |
| [Row Grouping](/grid/plugins/grouping-rows.md) | Group rows by field values with expand/collapse |
| [Column Grouping](/grid/plugins/grouping-columns.md) | Visual column grouping with nested headers |
| [Tree](/grid/plugins/tree.md) | Hierarchical tree data display |
| [Master-Detail](/grid/plugins/master-detail.md) | Expandable detail rows |
| [Pivot](/grid/plugins/pivot.md) | Pivot table transformation with aggregations |

### Layout & Display

| Plugin | Description |
| ------ | ----------- |
| [Shell](/grid/plugins/shell.md) | Header bar (title + toolbar) and collapsible tool-panel sidebar |
| [Pinned Columns](/grid/plugins/pinned-columns.md) | Pin columns to left or right edge |
| [Pinned Rows](/grid/plugins/pinned-rows.md) | Status bar with aggregations and custom panels |
| [Visibility](/grid/plugins/visibility.md) | Show/hide columns dynamically |
| [Column Virtualization](/grid/plugins/column-virtualization.md) | Performance optimization for many columns |
| [Responsive](/grid/plugins/responsive.md) | Card layout for narrow containers and mobile |
| [Tooltip](/grid/plugins/tooltip.md) | Popover tooltips for truncated header and cell text |

### Data & Export

| Plugin | Description |
| ------ | ----------- |
| [Export](/grid/plugins/export.md) | Export to CSV, Excel (XML), and JSON formats |
| [Print](/grid/plugins/print.md) | Print-optimized layout with styling |
| [Server-Side](/grid/plugins/server-side.md) | Lazy loading from remote data sources |

## Plugin Dependencies

Some plugins depend on other plugins to function. Dependencies can be **hard** (required) or **soft** (optional enhancement).

### Dependency Types

| Type | Behavior | Example |
| ---- | -------- | ------- |
| **Hard (Required)** | Plugin will throw an error if the dependency is missing | UndoRedoPlugin → EditingPlugin |
| **Soft (Optional)** | Plugin works without it, but gains extra features when present | VisibilityPlugin → ReorderPlugin |

### Current Plugin Dependencies

| Plugin | Depends On | Type | Reason |
| ------ | ---------- | ---- | ------ |
| **UndoRedoPlugin** | EditingPlugin | Hard | Tracks cell edit history for undo/redo |
| **ClipboardPlugin** | SelectionPlugin | Soft | Enables copy/paste of selected cells instead of entire grid |
| **VisibilityPlugin** | ReorderPlugin | Soft | Enables drag-to-reorder columns in visibility panel |

### Plugin Load Order

When using the **features API** (recommended), dependencies are resolved automatically — you don't need to worry about ordering.

When using the **plugin API** directly, dependencies must be loaded **before** the dependent plugin:

```typescript
// ✅ Correct - EditingPlugin loaded before UndoRedoPlugin
plugins: [
  new EditingPlugin(),
  new UndoRedoPlugin(),
]

// ❌ Wrong - throws error at runtime
plugins: [
  new UndoRedoPlugin(), // Error: EditingPlugin required
  new EditingPlugin(),
]
```

For declaring dependencies in your own custom plugins, see [Custom Plugins → Plugin Dependencies](/grid/plugin-development/custom-plugins.md#plugin-dependencies).

## Using Features (Recommended)

The features API is the simplest and recommended way to enable grid capabilities. It provides:

- **Declarative configuration** — describe _what_ you want, not _how_ to wire it up
- **Automatic dependency resolution** — features auto-resolve plugin dependencies in the correct order
- **Tree-shaking** via side-effect imports — only the features you import are included in your bundle
- **Framework adapter integration** — React, Vue, and Angular adapters expose features as typed props

#### Angular

```typescript
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import { GridEditingDirective } from '@toolbox-web/grid-angular/features/editing';
// In template:
// <tbw-grid [rows]="rows" [columns]="columns"
//   [selection]="'row'" [filtering]="{ debounceMs: 300 }" [editing]="'dblclick'" />
```

## Feature Reference (all features, side-effect import + accepted values)

One-line lookup for every feature. Import the side-effect once, then set the
matching `gridConfig.features.<name>` key (recommended) or the equivalent
framework prop. Paths below use the core package; adapters mirror them — replace
`@toolbox-web/grid` with `@toolbox-web/grid-react` / `-angular` / `-vue`.

| Feature key | Side-effect import | Accepted values |
|-------------|--------------------|-----------------|
| `selection` | `@toolbox-web/grid/features/selection` | `"cell"`, `"row"`, `"column"`, `"range"`, `["column", "row"]`, `{ mode: 'range', checkbox: true }` |
| `editing` | `…/features/editing` | `true`, `"click"`, `"dblclick"`, `"manual"`, `{ mode: 'row', editOn: 'click' }`, `{ mode: 'grid' }` (always-editable) |
| `multiSort` | `…/features/multi-sort` | `true`, `"single"`, `"multi"`, `{ maxSortColumns: 3 }` |
| `filtering` | `…/features/filtering` | `true`, `{ debounceMs: 200 }` |
| `clipboard` | `…/features/clipboard` | `true` (requires selection) |
| `undoRedo` | `…/features/undo-redo` | `true` (requires editing) |
| `contextMenu` | `…/features/context-menu` | `true`, `{ items: [...] }` |
| `reorderColumns` | `…/features/reorder-columns` | `true` |
| `reorderRows` | `…/features/reorder-rows` | `true` |
| `rowDragDrop` | `…/features/row-drag-drop` | `true`, `{ dropZone: 'employees' }` |
| `visibility` | `…/features/visibility` | `true` |
| `pinnedColumns` | `…/features/pinned-columns` | `true` |
| `pinnedRows` | `…/features/pinned-rows` | `true`, `{ slots: [{ position: 'bottom', aggregators: { … } }] }` |
| `groupingColumns` | `…/features/grouping-columns` | `true`, `{ columnGroups: [...] }` |
| `groupingRows` | `…/features/grouping-rows` | `{ groupOn: (row) => [row.department] }` |
| `tree` | `…/features/tree` | `{ childrenField: 'children' }` |
| `columnVirtualization` | `…/features/column-virtualization` | `true` |
| `masterDetail` | `…/features/master-detail` | `{ detailRenderer: (row, rowIndex) => '<div>…</div>' }` |
| `responsive` | `…/features/responsive` | `true`, `{ breakpoint: 768 }` |
| `export` | `…/features/export` | `true`, `{ fileName: 'data' }` |
| `print` | `…/features/print` | `true` |
| `pivot` | `…/features/pivot` | `{ rowGroupFields: ['region'], columnGroupFields: ['quarter'], valueFields: [{ field: 'revenue', aggFunc: 'sum' }] }` |
| `serverSide` | `…/features/server-side` | `{ dataSource: async (params) => … }` |
| `tooltip` | `…/features/tooltip` | `true`, `{ header: true, cell: false }` |
| `stickyRows` | `…/features/sticky-rows` | `{ isSticky: 'isSection' }`, `{ isSticky: (row) => row.isHeader, mode: 'stack', maxStacked: 3 }` |

Import every feature at once (prototyping only): `import '@toolbox-web/grid/features';`

### Import All Plugins

For rapid prototyping when bundle size is not critical:

```typescript
import { SelectionPlugin, FilteringPlugin, EditingPlugin } from '@toolbox-web/grid/all';
```

This imports the core grid and all 25 plugin modules. Use the `plugins` array to configure them:

```typescript
grid.gridConfig = {
  plugins: [
    new SelectionPlugin({ mode: 'row' }),
    new FilteringPlugin(),
    new EditingPlugin({ editOn: 'dblclick' }),
  ],
};
```

### Accessing Plugin Instances

Whether you use features or plugins, access runtime APIs the same way:

```typescript
const selection = grid.getPluginByName('selection');
if (selection) {
  selection.selectAll();
  selection.clearSelection();
  const ranges = selection.getSelectedRanges();
}
```

## Plugin Imperative API Reference (`grid.getPluginByName(name)`)

`grid.getPluginByName(name)` returns the live plugin instance (or `undefined` if
not loaded). The `name` is the plugin's registered key (NOT the class name).
Key imperative methods per plugin:

| Plugin | `name` key | Key imperative methods |
|--------|-----------|------------------------|
| SelectionPlugin | `selection` | `selectAll()`, `clearSelection()`, `getSelectedRanges()`, `getSelection()`, `selectRows(idx[])`, `getSelectedRowIndices()`, `getSelectedRows()`, `getSelectedColumns()` |
| EditingPlugin | `editing` | (dirtyTracking) `isDirty(rowId)`, `isPristine(rowId)`, `getDirtyRows()`, `markAsPristine(rowId)`, `markAllPristine()`, `markAsDirty(rowId)`, `revertRow(rowId)`, `getOriginalRow(rowId)` |
| FilteringPlugin | `filtering` | `setFilter()`, `setFilterModel()`, `clearAllFilters()`, `clearFieldFilter()` (all accept `{ silent: true }`), `getStaleFilters()`, `getBlankMode(field)`, `toggleBlankFilter(field, mode)` |
| MultiSortPlugin | `multiSort` | `getSortModel()`, `setSortModel(model)`, `clearSort()`, `getSortIndex(field)`, `getSortDirection(field)` |
| TreePlugin | `tree` | `expand(key)`, `collapse(key)`, `toggle(key)`, `expandAll()`, `collapseAll()`, `isExpanded(key)`, `getExpandedKeys()`, `expandToKey(key)`, `getFlattenedRows()`, `getRowByKey(key)` |
| GroupingRowsPlugin | `groupingRows` | `expand(key)`, `collapse(key)`, `toggle(key)`, `expandAll()`, `collapseAll()`, `isExpanded(key)`, `getExpandedGroups()`, `getGroupState()`, `getFlattenedRows()`, `setGroups(g)`, `getGroups()`, `setGroupRows(key, rows)`, `clearGroupRows(key?)` |
| GroupingColumnsPlugin | `groupingColumns` | `isGroupingActive()`, `getGroups()`, `getGroupColumns(groupId)`, `refresh()` |
| MasterDetailPlugin | `masterDetail` | `expand(rowIndex)`, `collapse(rowIndex)`, `toggle(rowIndex)`, `expandAll()`, `collapseAll()`, `isExpanded(rowIndex)`, `getExpandedRows()`, `getDetailElement(rowIndex)`, `getDetailData(rowIndex)`, `isDetailLoading(rowIndex)` |
| PivotPlugin | `pivot` | `enablePivot()`, `disablePivot()`, `isPivotActive()`, `getPivotResult()`, `setRowGroupFields(f)`, `setColumnGroupFields(f)`, `setValueFields(f)`, `refresh()`, `expandAll()`, `collapseAll()`, `getExpandedGroups()` |
| ClipboardPlugin | `clipboard` | `copy()`, `copy({ columns, rowIndices, includeHeaders })`, `copyRows(idx[], opts)`, `getSelectionAsText(opts)`, `paste()` |
| ExportPlugin | `export` | `exportCsv(opts)`, `exportExcel(opts)`, `exportJson(opts)`, `export()` (rows), `formatCsv(rows)`, `formatExcel(rows)`, `getResolvedColumns()` |
| VisibilityPlugin | `visibility` | `show()`, `hide()`, `toggle()`, `isPanelVisible()`, `isColumnVisible(field)`, `setColumnVisible(field, v)`, `toggleColumn(field)`, `showAll()`, `getVisibleColumns()`, `getHiddenColumns()` |
| PinnedColumnsPlugin | `pinnedColumns` | `setPinPosition(field, pos)`, `refreshStickyOffsets()`, `getLeftPinnedColumns()`, `getRightPinnedColumns()`, `clearStickyPositions()` |
| PinnedRowsPlugin | `pinnedRows` | `refresh()`, `addPanel(p)`, `removePanel(id)`, `addAggregationRow(c)`, `removeAggregationRow(id)` |
| ReorderPlugin | `reorderColumns` | `getColumnOrder()`, `moveColumn(field, toIndex)`, `setColumnOrder(order)`, `resetColumnOrder()` |
| RowDragDropPlugin | `rowDragDrop` | `moveRow(fromIndex, toIndex)`, `canMoveRow(fromIndex, toIndex)` |
| ColumnVirtualizationPlugin | `columnVirtualization` | `getIsVirtualized()`, `getVisibleColumnRange()`, `scrollToColumn(idx)`, `getTotalWidth()` |
| PrintPlugin | `print` | `isPrinting()`, `print()`, `print({ orientation, title, maxRows })` |
| UndoRedoPlugin | `undoRedo` | `undo()`, `redo()`, `canUndo()`, `canRedo()`, `clearHistory()`, `getUndoStack()`, `getRedoStack()`, `recordEdit(idx, field, old, new)`, `beginTransaction()`, `endTransaction()` |

Inter-plugin queries (`grid.query(name, ...)`) — used when one plugin reads
another without a hard dependency. SelectionPlugin exposes: `'getSelection'`,
`'selectRows'`, `'getSelectedRowIndices'`, `'getSelectedRows'`,
`'getSelectedColumns'`.

## Using Plugins (Advanced)

For building custom plugins or when you need to instantiate plugin classes yourself (e.g., to pass constructor-only options or extend `BaseGridPlugin`), use the plugin API directly. The result is identical to using features — this is just a different way to configure the same capabilities.

### Import Paths

The grid package provides multiple entry points for different use cases:

| Entry Point | What It Includes | Tree-Shaking |
| ----------- | ---------------- | ------------ |
| `@toolbox-web/grid` | Core grid only (auto-registers `<tbw-grid>`) | N/A |
| `@toolbox-web/grid/all` | Core + **all** plugins bundled | No |
| `@toolbox-web/grid/plugins/*` | Individual plugin (e.g., `/plugins/selection`) | Yes |

> **Important:** Do not import from both `@toolbox-web/grid` and `@toolbox-web/grid/all` in the same application. The `all` entry point already includes the core grid, so importing both will register the custom element twice.

#### Plugin Import Patterns

**For production apps using plugin API directly (best tree-shaking):**
```typescript
// Import core grid
import '@toolbox-web/grid';

// Import only the plugins you need
import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';
import { FilteringPlugin } from '@toolbox-web/grid/plugins/filtering';
import { EditingPlugin } from '@toolbox-web/grid/plugins/editing';
```

**For prototyping (includes core grid + all plugins):**
```typescript
// Import everything at once (includes core grid + all plugins)
import { SelectionPlugin, FilteringPlugin, EditingPlugin } from '@toolbox-web/grid/all';
```

### Registration

Pass plugin instances to the `gridConfig.plugins` array:

```typescript
import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');

grid.gridConfig = {
  columns: [...],
  plugins: [
    new SelectionPlugin({ mode: 'row' }),
    new FilteringPlugin({ debounceMs: 300 }),
  ],
};
```

## Plugin Configuration

Each plugin accepts a configuration object:

```typescript
// Selection plugin options
new SelectionPlugin({
  mode: 'row',
  multiSelect: true,
  checkbox: true,
});

// Filtering plugin options
new FilteringPlugin({
  debounceMs: 200,
  caseSensitive: false,
});

// Export plugin options
new ExportPlugin({
  fileName: 'grid-export',
  includeHeaders: true,
  onlyVisible: true,
});
```

## Creating Custom Plugins

The grid's plugin system lets you build fully custom functionality. Plugins extend [`BaseGridPlugin`](/grid/api/plugin-development/classes/basegridplugin.md) and can hook into lifecycle events, process rows/columns, handle keyboard events, and inject CSS.

For the full development guide including lifecycle hooks, plugin communication, the query system, and styling patterns, see [Writing Custom Plugins](/grid/plugin-development/custom-plugins.md).

## Known Incompatibilities

Some plugin combinations conflict and should not be used together. A development-mode warning is shown when conflicts are detected:

| Plugin A | Plugin B | Reason |
|----------|----------|--------|
| GroupingRowsPlugin | TreePlugin | Both transform the entire row model in different ways |
| GroupingRowsPlugin | PivotPlugin | Pivot creates its own aggregated row/column structure |
| TreePlugin | PivotPlugin | Pivot replaces the data structure; tree hierarchy cannot coexist |
| ServerSidePlugin | GroupingRowsPlugin | Grouping needs the full dataset; server-side loads blocks lazily |
| ServerSidePlugin | TreePlugin | Tree needs the full hierarchy; server-side cannot provide children on demand |
| ServerSidePlugin | PivotPlugin | Pivot needs the full dataset for aggregation |

## See Also

- [Common Patterns](/grid/guides/common-patterns.md) — Real-world recipes combining plugins (all frameworks)
- [Getting Started](/grid/getting-started.md) — Quick setup with features API
- [Custom Plugin Development](/grid/plugin-development/custom-plugins.md) — Build your own plugins
- [Architecture](/grid/architecture.md) — How the plugin system fits into the grid's internals
- [Performance Guide](/grid/guides/performance.md) — Bundle optimization with tree-shakeable features

---

# Accessibility

> How @toolbox-web/grid implements WAI-ARIA grid patterns, keyboard navigation, screen reader support, and high contrast mode.

`@toolbox-web/grid` follows the [WAI-ARIA Grid Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) to provide an accessible data grid experience. This page documents the ARIA attributes, keyboard interactions, and best practices.

## Our accessibility commitment

We target **WCAG 2.1 Level AA** out of the box, with no configuration required. That means:

- **Every interactive operation** (sort, filter, select, edit, expand, reorder, resize, group, paste) is reachable from the keyboard alone — no mouse-only paths.
- **Every state change** (sort applied, filter cleared, row selected, edit committed) is announced to assistive technology via the grid's built-in `aria-live` region.
- **Every visual signal** (focus, selection, error state, sort direction) has a non-color cue (icon, text, ARIA attribute) so the grid works without color perception.
- **Windows High Contrast / forced-colors** is supported automatically — the grid maps every themable surface to system colors via `@media (forced-colors: active)`.
- **Reduced motion** is respected — animations, expand/collapse transitions, and scroll smoothing disable under `prefers-reduced-motion: reduce`.
- **Focus is never lost** — after editing, deleting, sorting, or filtering, the grid restores focus to a sensible cell.

See the [full WCAG 2.1 AA conformance table](#wcag-compliance-checklist) below for the criteria we test against.

> **Filing accessibility issues:** If you find an a11y bug, please open an issue with the screen reader / browser / OS you used and what was announced (or wasn't). A11y bugs are treated as P0.

## ARIA Roles & Attributes

The grid applies the following ARIA roles and attributes automatically:

### Grid Structure

| Element | Role | Attributes |
|---------|------|-----------|
| `<tbw-grid>` | `grid` (or `treegrid` when [Tree](/grid/plugins/tree.md) or [Row Grouping](/grid/plugins/grouping-rows.md) is active) | `aria-rowcount`, `aria-colcount`, `aria-multiselectable` |
| Header container | `rowgroup` | — |
| Header row | `row` | `aria-rowindex="1"` |
| Header cell | `columnheader` | `aria-sort`, `aria-colindex` |
| Body container | `rowgroup` | — |
| Data row | `row` | `aria-rowindex`, `aria-selected`, `aria-expanded`, `aria-level` / `aria-setsize` / `aria-posinset` (under `treegrid`) |
| Data cell | `gridcell` | `aria-colindex`, `aria-selected`, `aria-readonly` |

### Dynamic Attributes

| Attribute | Applied When | Values |
|-----------|-------------|--------|
| `aria-sort` | Column is sorted | `ascending`, `descending`, `none` |
| `aria-selected` | Row or cell is selected | `true`, `false` |
| `aria-expanded` | Row grouping/tree is active (rows with children) | `true`, `false` |
| `aria-label` | `gridAriaLabel` is set, or `shell.header.title` provides a fallback (suppressed when `gridAriaLabelledBy` is set) | string |
| `aria-labelledby` | `gridAriaLabelledBy` is set | id-ref |
| `aria-describedby` | `gridAriaDescribedBy` is set | id-ref |
| `aria-roledescription` | `gridAriaRoleDescription` is set (overrides the AT-announced role name; use sparingly — value should still describe a grid widget) | string |
| `aria-level` | [Tree](/grid/plugins/tree.md) or [Row Grouping](/grid/plugins/grouping-rows.md) plugin is active (1-based hierarchical depth) | `1`, `2`, … |
| `aria-setsize` | [Tree](/grid/plugins/tree.md) or [Row Grouping](/grid/plugins/grouping-rows.md) plugin is active (sibling count at this level) | integer |
| `aria-posinset` | [Tree](/grid/plugins/tree.md) or [Row Grouping](/grid/plugins/grouping-rows.md) plugin is active (1-based position among siblings) | integer |
| `aria-multiselectable` | Selection plugin allows multi-select | `true` |
| `aria-readonly` | Cell is not editable | `true` |
| `aria-rowindex` | Always (1-based) | Row position in full dataset |
| `aria-colindex` | Always (1-based) | Column position |

## Keyboard Navigation

The grid implements full keyboard navigation following the WAI-ARIA grid pattern:

### Basic Navigation

| Key | Action |
|-----|--------|
| <kbd>↑</kbd> / <kbd>↓</kbd> | Move focus between rows |
| <kbd>←</kbd> / <kbd>→</kbd> | Move focus between cells |
| <kbd>Home</kbd> | Move to first cell in row |
| <kbd>End</kbd> | Move to last cell in row |
| <kbd>Ctrl</kbd> + <kbd>Home</kbd> | Move to first cell in grid |
| <kbd>Ctrl</kbd> + <kbd>End</kbd> | Move to last cell in grid |
| <kbd>PgUp</kbd> | Scroll up one viewport |
| <kbd>PgDn</kbd> | Scroll down one viewport |
| <kbd>⇥ Tab</kbd> | Move to next cell (wraps to next row) |
| <kbd>⇧ Shift</kbd> + <kbd>⇥ Tab</kbd> | Move to previous cell (wraps to previous row) |

### Plugin-Specific Shortcuts

Keyboard shortcuts that depend on a plugin being installed are documented on each plugin's own page — that's the source of truth and stays in sync with the implementation:

- [**Selection**](/grid/plugins/selection.md#keyboard-shortcuts) — <kbd>Space</kbd>, <kbd>Shift</kbd> + arrows / <kbd>PgUp</kbd> / <kbd>PgDn</kbd> / <kbd>Ctrl</kbd> + <kbd>Home</kbd>/<kbd>End</kbd>, <kbd>Ctrl</kbd> + <kbd>A</kbd>, <kbd>Esc</kbd>
- [**Editing**](/grid/plugins/editing.md#keyboard-shortcuts-row-mode) — <kbd>Enter</kbd> (start row edit / commit), <kbd>F2</kbd> (single-cell edit), <kbd>Tab</kbd> / <kbd>Shift</kbd> + <kbd>Tab</kbd>, <kbd>Esc</kbd> (cancel)
- [**Clipboard**](/grid/plugins/clipboard.md#keyboard-shortcuts) — <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>C</kbd> / <kbd>X</kbd> / <kbd>V</kbd>
- [**Context Menu**](/grid/plugins/context-menu.md) — <kbd>Shift</kbd> + <kbd>F10</kbd> or the dedicated <kbd>☰ Menu</kbd> key opens the menu at the focused cell; <kbd>↑</kbd>/<kbd>↓</kbd> navigates, <kbd>Enter</kbd>/<kbd>Space</kbd> activates, <kbd>Esc</kbd> closes
- [**Row Grouping**](/grid/plugins/grouping-rows.md) — <kbd>Space</kbd> toggles expand/collapse on a group or tree node

## Focus Management

### Focus Indicators

The grid uses visible focus indicators that meet WCAG 2.1 Level AA requirements:

```css
tbw-grid {
  /* Customize focus ring */
  --tbw-color-focus-ring: #2563eb;
}
```

The focus ring is 2px solid and uses `outline` (not `border`) so it doesn't affect layout.

### Focus Trapping

When editing a cell, focus is trapped within the editor until the user commits (Enter/Tab) or cancels (Escape). Overlay editors (date pickers, dropdowns) use `registerExternalFocusContainer()` to extend the focus trap.

### Roving Tabindex

The grid uses a roving tabindex pattern:
- Only the currently focused cell has `tabindex="0"`
- All other cells have `tabindex="-1"`
- This means **Tab** moves focus out of the grid, and **Shift+Tab** moves focus back to the last focused cell

This matches the [WAI-ARIA grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) — a grid is *one* tab stop in the page's tab order. Once focus enters, arrow keys navigate.

### Focus restoration

After every operation that destroys and recreates row DOM (sort, filter, edit-commit, row removal, expand/collapse, virtualization scroll-back), the grid restores focus to the most logical cell — the same row by identity if it still exists, otherwise the same row index, otherwise the nearest surviving row in the same column. You do not need to do anything for this to work — it's automatic.

### External focus containers

Overlay UIs that float *outside* the grid's DOM (date pickers, dropdowns, autocompletes used by editors or custom renderers) need to be registered so the grid's focus trap and outside-click handling treat them as part of the grid:

```ts
const cleanup = grid.registerExternalFocusContainer(popoverEl);
// ...later, when the popover closes:
cleanup();
```

Without this, clicking inside the popover commits the active edit and closes it. With it, the popover is treated as an extension of the focused cell.

## Screen Reader Support

### Labels and Descriptions

Provide accessible labels for screen readers:

```html
<tbw-grid aria-label="Employee directory">
```

Or reference a visible heading:

```html
<h2 id="grid-heading">Employees</h2>
<tbw-grid aria-labelledby="grid-heading">
```

### Live Regions

The grid uses `aria-live` regions to announce dynamic changes to screen readers:
- Sort changes ("Sorted by Name, ascending")
- Filter changes ("Filter applied on Name", "All filters cleared")
- Group expand/collapse ("Group Engineering expanded, 5 rows")
- Selection changes ("3 rows selected")
- Editing lifecycle ("Editing row 1", "Row 1 saved")

### Configuring Announcements

You can disable or customize live region announcements via the [`a11y`](/grid/api/core/interfaces/a11yconfig.md) config — see [`A11yMessages`](/grid/api/core/interfaces/a11ymessages.md) for the full list of overridable messages and their signatures:

```typescript
// Disable all announcements
grid.gridConfig = {
  a11y: { announcements: false },
};

// Override messages for internationalization
grid.gridConfig = {
  a11y: {
    messages: {
      sortApplied: (col, dir) => `Trié par ${col}, ${dir}`,
      sortCleared: () => 'Tri effacé',
      filterApplied: (col) => `Filtre appliqué sur ${col}`,
      filterCleared: (col) => `Filtre effacé de ${col}`,
      allFiltersCleared: () => 'Tous les filtres effacés',
      groupExpanded: (name, count) => `Groupe ${name} développé, ${count} lignes`,
      groupCollapsed: (name) => `Groupe ${name} réduit`,
      selectionChanged: (count) => `${count} lignes sélectionnées`,
      editingStarted: (rowIndex) => `Édition de la ligne ${rowIndex + 1}`,
      editingCommitted: (rowIndex) => `Ligne ${rowIndex + 1} enregistrée`,
      dataLoaded: (count) => `${count} lignes chargées`,
    },
  },
};
```

Only override the messages you need — defaults (English) are used for the rest.

### Column Headers

Column headers include:
- Column name via text content
- Sort direction via `aria-sort`
- Filter state via `aria-description` ("Filtered")

### Testing with screen readers

The grid is tested against NVDA, VoiceOver, and JAWS in CI-adjacent environments. When testing in your own app, here's what a screen-reader user should hear for the core flows. If your output diverges substantially from this, that's likely an a11y bug worth filing.

**NVDA (Windows, Firefox or Chrome):**
1. Download [NVDA](https://www.nvaccess.org/download/) (free) and start it.
2. Tab into the grid — you should hear `"<grid label>, grid, <N> rows, <M> columns"` followed by the focused cell.
3. Press <kbd>↓</kbd> — `"<value>, column <name>, row <n> of <total>"`.
4. Press <kbd>Enter</kbd> on a header — `"sorted ascending"` / `"sorted descending"` (and the announcement is repeated via the live region).
5. Use NVDA's *Browse Mode* toggle (<kbd>Insert</kbd>+<kbd>Space</kbd>) to switch to virtual cursor — table-reading shortcuts (<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+arrows) should walk the grid as a native HTML table.

**VoiceOver (macOS, Safari):**
1. Enable VoiceOver: <kbd>⌘</kbd>+<kbd>F5</kbd>.
2. Use <kbd>VO</kbd>+<kbd>→</kbd> to enter the grid — you should hear the label and dimensions.
3. <kbd>VO</kbd>+<kbd>Shift</kbd>+<kbd>↓</kbd> enters interaction mode; then arrow keys navigate cells with full column + row context.
4. Rotor (<kbd>VO</kbd>+<kbd>U</kbd>) → *Tables* should list the grid for jump-navigation.

**JAWS (Windows):**
- Use *Virtual PC Cursor* (default) for browse, *Forms Mode* (<kbd>Enter</kbd>) for grid interaction. Table layer (<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+arrows) walks cells.

**iOS VoiceOver / Android TalkBack:**
- Touch a cell — the column header, value, row/column position, and any selection/expand state are announced.
- Swipe right/left moves through cells; swipe up/down navigates by row.

**What you should *not* hear** — these would indicate a bug worth filing:
- Empty cell announcements (`"blank"`) when the cell has visible content
- Position announced as `"row 1 of 1"` when there are clearly more rows (virtualization metadata is wrong)
- Sort/filter changes never announced (live region not wired up)
- Editing committed without any feedback

## Reduced Motion

The grid respects the `prefers-reduced-motion: reduce` user preference automatically. When set, the grid:

- **Disables row animations** ([row animation API](/grid/core.md#row-animation) skips transitions)
- **Disables expand/collapse transitions** in tree, grouping, and master-detail plugins
- **Disables scroll smoothing** in programmatic `scrollToRow()` / `scrollToCell()` calls (jumps instead of animating)
- **Disables loading-state crossfade** (instant swap instead)

You don't need to do anything to opt in. If you have custom renderers or plugins that animate, honor the preference:

```css
@media (prefers-reduced-motion: reduce) {
  .my-cell-animation { transition: none; animation: none; }
}
```

## High Contrast Mode

### Using CSS Custom Properties

The grid's CSS variable system makes high contrast easy:

```css
/* High contrast theme */
tbw-grid.high-contrast {
  --tbw-color-bg: #000;
  --tbw-color-fg: #fff;
  --tbw-color-border: #fff;
  --tbw-color-header-bg: #1a1a1a;
  --tbw-color-row-hover: #333;
  --tbw-color-focus-ring: #ffff00;
  --tbw-color-accent: #00ffff;
}
```

### Pre-built Contrast Theme

```typescript
import '@toolbox-web/grid/themes/dg-theme-contrast.css';
```

### Windows High Contrast Mode

The grid ships with a built-in `@media (forced-colors: active)` block that remaps all theming variables to Windows system colors (`CanvasText`, `Canvas`, `Highlight`, `HighlightText`). Focus rings and selected rows are also overridden to use `Highlight`. No extra configuration needed — it works automatically.

If you write custom renderers, follow the same pattern so your cells stay legible under forced-colors:

```css
.my-status-badge {
  background: var(--tbw-color-accent);
  color: var(--tbw-color-on-accent);
  border: 1px solid transparent;
}

@media (forced-colors: active) {
  .my-status-badge {
    background: Canvas;
    color: CanvasText;
    border: 1px solid CanvasText; /* outline so the badge stays distinguishable */
    forced-color-adjust: none;     /* opt out of the browser's automatic remap */
  }
}
```

Key rules: prefer **system color keywords** (`CanvasText`, `Canvas`, `LinkText`, `ButtonText`, `Highlight`, `HighlightText`, `Mark`, `MarkText`) inside `forced-colors` media queries, and never rely on color alone — always pair with a border, underline, or icon.

## Accessibility-First Patterns

These patterns are how we keep the grid accessible — and how you should keep your customizations accessible too.

### 1. Never replace content with color alone

When you write a `renderer` for status, error, or category cells, give it text or an icon — not just a colored dot. The grid's built-in renderers (selection checkbox, sort indicator, expand chevron, filter button) all follow this rule.

```ts
// ❌ Color-only — invisible to screen readers, fails in forced-colors
{ field: 'status', renderer: ({ value }) => `<span class="dot dot-${value}"></span>` }

// ✅ Text + color — readable everywhere
{ field: 'status', renderer: ({ value }) => `<span class="dot dot-${value}" aria-label="${value}">${value}</span>` }
```

### 2. Don't suppress focus indicators

The default focus ring is 2px solid `var(--tbw-color-focus-ring)` using `outline` (not `border`) so it doesn't reflow. **Never** set `outline: none` without providing an equivalent indicator — WCAG 2.4.7 fails immediately, and forced-colors users lose the only signal they have.

### 3. Use semantic `<button>` / `<a>` inside renderers

Custom action buttons should be real `<button>` elements (or `<a href>` for navigation), not clickable `<div>`s. They inherit keyboard activation, focus, and screen-reader role for free. The grid's roving-tabindex pattern still works because the renderer is inside a `gridcell` — pressing <kbd>Enter</kbd> activates the button.

### 4. Label fragmented controls

If a cell renders multiple controls (e.g. edit + delete buttons), each needs a discrete accessible name — usually via `aria-label`:

```ts
viewRenderer: ({ row }) => `
  <button aria-label="Edit ${row.name}">✏️</button>
  <button aria-label="Delete ${row.name}">🗑️</button>
`
```

A bare emoji or icon has no name; screen readers announce `"button"` and the user can't tell them apart.

### 5. Don't override keyboard handling without consulting the WAI-ARIA pattern

The grid implements the [WAI-ARIA Grid Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/). If you stop event propagation in a `keydown` handler on a cell, you may break navigation. If you really need to override (rare), do it only for the specific keys you care about and let the rest bubble.

## WCAG Compliance Checklist

| Criterion | Level | Status | Notes |
|-----------|-------|--------|-------|
| 1.1.1 Non-text Content | A | ✅ | Icons have text alternatives |
| 1.3.1 Info and Relationships | A | ✅ | ARIA roles convey structure |
| 1.3.2 Meaningful Sequence | A | ✅ | DOM order matches visual order |
| 1.4.1 Use of Color | A | ✅ | Status not conveyed by color alone |
| 1.4.3 Contrast (Min) | AA | ✅ | Default theme meets 4.5:1 ratio |
| 1.4.11 Non-text Contrast | AA | ✅ | Focus indicators visible at 3:1 |
| 2.1.1 Keyboard | A | ✅ | All functions accessible via keyboard |
| 2.1.2 No Keyboard Trap | A | ✅ | Tab exits the grid; Escape exits editors |
| 2.4.3 Focus Order | A | ✅ | Logical focus order follows grid structure |
| 2.4.7 Focus Visible | AA | ✅ | Clear focus indicators |
| 4.1.2 Name, Role, Value | A | ✅ | ARIA attributes on all interactive elements |

## What's Automatic

The grid handles most accessibility concerns out of the box:

- **ARIA roles & attributes** — `role="grid"`, `role="row"`, `role="gridcell"`, `aria-rowcount`, `aria-colcount`, `aria-rowindex`, `aria-colindex` are always set. When the [Tree](/grid/plugins/tree.md) or [Row Grouping](/grid/plugins/grouping-rows.md) plugin is active, the rows-body upgrades to `role="treegrid"` and every row carries `aria-level` / `aria-setsize` / `aria-posinset` per the [WAI-ARIA Treegrid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/) so screen readers can announce hierarchical position.
- **Keyboard navigation** — Arrow keys, Tab, Enter, Home/End, PgUp/PgDn all work by default (core feature, not a plugin)
- **Column headers** — Always rendered with `role="columnheader"`; cannot be hidden
- **Column type inference** — Types (`number`, `date`, `boolean`) are auto-detected from the first data row
- **Grid label** — Auto-derived from the shell title (`<tbw-grid-header title="...">` or `shell.header.title` config)
- **Windows High Contrast** — `forced-colors` media query is built into core CSS
- **Live announcements** — Sort, filter, selection, grouping, and editing changes are announced via `aria-live` regions (configurable via `a11y` config)
- **Plugin ARIA** — Selection, editing, filtering, tree, and grouping plugins manage their own ARIA attributes (`aria-selected`, `aria-readonly`, `aria-expanded`, `aria-multiselectable`, `aria-description`)

## Developer Responsibilities

These require explicit action:

1. **Provide a grid label when not using a shell** — Without `<tbw-grid-header title="...">`, set `gridAriaLabel` in config, or set `gridAriaLabelledBy` to the `id` of an existing heading next to the grid (`aria-labelledby` wins per WAI-ARIA precedence and suppresses `aria-label` to avoid conflicting names), or add `aria-label` directly on the element
2. **Test with screen readers** — NVDA (Windows), VoiceOver (macOS), Orca (Linux)
3. **Don't override keyboard handling** — The grid follows WAI-ARIA patterns; custom key listeners may conflict
4. **Use the contrast theme for additional a11y** — Import `dg-theme-contrast.css` for higher contrast beyond the built-in forced-colors support

## See Also

  - [Selection Plugin](/grid/plugins/selection.md): Cell, row, and range selection with full keyboard support
  - [Editing Plugin](/grid/plugins/editing.md): Inline cell editing with Tab/Enter/Escape navigation
  - [Theming](/grid/guides/theming.md): CSS custom properties, high contrast mode, and visual customization
  - [WAI-ARIA Grid Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/): The W3C specification this grid follows

---

# Automated testing

> Write reliable Playwright, Cypress, and WebdriverIO tests against @toolbox-web/grid using its stable CSS classes, data attributes, ARIA roles, and ready() / 'render' event lifecycle hooks.

`@toolbox-web/grid` is built to be tested. Every surface a test script needs — CSS class names, `data-*` attributes, ARIA roles, lifecycle promises, and events — is a **stable, documented public API**. You should never have to reverse-engineer a selector from DevTools to assert on a cell.

This guide shows you what those surfaces are and how to drive the grid from Playwright, Cypress, and WebdriverIO.

:::tip[For manual debugging]
This page is about **automated tests in CI**. If you're poking at a grid in the DevTools console to diagnose a bug, see [Troubleshooting → How to debug the grid](/grid/guides/troubleshooting.md#how-to-debug-the-grid) — same selectors, different audience.
:::

## Why the grid is testable

| Surface | What you get | Stability |
|---|---|---|
| **CSS classes** (`GridClasses`) | `data-grid-row` (row container), `cell` (data cell), `header-row`, `header-cell`, `selected`, `editing`, `sorted-asc`, `sorted-desc`, `focused`, … | Semver-stable, `@since 0.1.1` |
| **Data attributes** (`GridDataAttrs`) | `data-field="<col>"`, `data-row="<rowIndex>"`, `data-group-key` | Semver-stable |
| **CSS selectors** (`GridSelectors`) | Prebuilt selectors: `DATA_ROW`, `DATA_CELL`, `SELECTED_ROWS`, `EDITING_CELL`, `CELL_BY_FIELD(field)`, … | Semver-stable |
| **ARIA roles + attributes** | `role="grid"`, `role="row"`, `role="gridcell"`, `role="columnheader"`, `aria-rowindex`, `aria-colindex`, `aria-sort`, `aria-selected`, `aria-expanded` | Semver-stable — also the WCAG contract |
| **Lifecycle hook** | `grid.ready()` — `Promise` resolved after first render | Public API |
| **Render event** | `grid.addEventListener('render', …)` — fires once per scheduler flush | Public API, `@since 2.15.0` |

Locator strategy in priority order:

1. **ARIA selectors first** (`getByRole`, `aria-rowindex`, `aria-colindex`) — they match what assistive tech sees, so a passing accessibility test is also a passing functional test.
2. **`data-field` + `data-row`** for cell lookups when you know the column field and want a specific row.
3. **`GridClasses` constants** for state assertions (`.selected`, `.editing`, `.sorted-asc`).
4. **Never** depend on framework wrapper class names (React/Vue/Angular wrappers generate them; they change between builds).

## The stable selector surface

### Finding cells

```ts
// All rendered data rows
'tbw-grid .data-grid-row';

// The cell at row 42, column "email" (works for any data field)
'tbw-grid .cell[data-row="42"][data-field="email"]';

// Every cell in a given column
'tbw-grid .cell[data-field="salary"]';

// Header cell for a column
'tbw-grid .header-cell[data-field="email"]';

// Currently-editing cell
'tbw-grid .cell.editing';

// Selected rows
'tbw-grid .data-grid-row.selected';
```

### Finding cells by ARIA (recommended for accessibility parity)

```ts
// Header cell — page.getByRole('columnheader', { name: 'Email' })
'tbw-grid [role="columnheader"]:has-text("Email")';

// Any data cell at the visible row index N (1-based, ARIA convention)
`tbw-grid [role="row"][aria-rowindex="${n}"] [role="gridcell"]`;

// Cell at row N, column M (both 1-based)
`tbw-grid [role="row"][aria-rowindex="${n}"] [role="gridcell"][aria-colindex="${m}"]`;

// Sorted columns and their direction
'tbw-grid [role="columnheader"][aria-sort="ascending"]';
'tbw-grid [role="columnheader"][aria-sort="descending"]';

// Selected rows
'tbw-grid [role="row"][aria-selected="true"]';
```

> **`data-row` vs `aria-rowindex`:** `data-row` is the **0-based index** of the row in the current processed data array (attached to each cell). `aria-rowindex` is the **1-based row position** for assistive tech (attached to each row element), with the header counting as row 1. Pick one and be consistent.

## Waiting for the grid

The grid renders asynchronously. **Never `setTimeout`** — wait on the real signals.

### Wait for first render

`grid.ready()` returns a `Promise` that resolves after the grid has mounted, registered plugins, and completed its first render. Awaitable from any test framework via `page.evaluate()` (Playwright) or equivalent.

### Test setup — make `queryGrid` available to the page

Tests run their callbacks inside the **browser**, not Node, so they can't `import` from `@toolbox-web/grid` directly inside a `page.evaluate` body. You have two ways to make `queryGrid` reachable from inside the browser context — pick the one that matches how your app loads the grid:

**If your app uses an ESM bundler (Vite, Webpack, Next.js, Astro, etc.)** — expose `queryGrid` on `window` once, from your app's entry file or a test-only entry:

```ts
// src/test-setup.ts — loaded by your app's dev server during tests
import { queryGrid } from '@toolbox-web/grid';

declare global {
  interface Window {
    queryGrid: typeof queryGrid;
  }
}

window.queryGrid = queryGrid;
```

Now `window.queryGrid('tbw-grid')` is fully typed inside every test — no `as HTMLElement & { ... }` casts.

**If your app loads the [UMD bundle](/grid/getting-started.md#plain-javascript-no-build-step)** — `window.TbwGrid.queryGrid(...)` is already available, no setup needed. Substitute `window.TbwGrid.queryGrid` for `window.queryGrid` in every example below.

#### Playwright

```ts
await page.evaluate(async () => {
  const grid = window.queryGrid('tbw-grid');
  await grid?.ready();
});
```

#### Cypress

```ts
cy.window().then(async (win) => {
  const grid = win.queryGrid('tbw-grid');
  await grid?.ready();
});
```

#### WebdriverIO

```ts
await browser.execute(async () => {
  const grid = window.queryGrid('tbw-grid');
  await grid?.ready();
});
```

> `queryGrid` returns a fully-typed `DataGridElement<T>` — no manual `HTMLElement & { ... }` intersections, and it's multi-version-safe (it finds the grid even if more than one major version is loaded on the page).

### Wait for a subsequent render

After you trigger a sort, filter, edit, or data swap, wait for the next `'render'` event before asserting on the new DOM.

#### Playwright

```ts
// Wait for the next render after triggering some action
async function waitForRender(page) {
  await page.evaluate(
    () => new Promise<void>((resolve) =>
      window.queryGrid('tbw-grid')!.addEventListener('render', () => resolve(), { once: true })
    ),
  );
}

await page.locator('[role="columnheader"]:has-text("Salary")').click();
await waitForRender(page);
```

#### Cypress

```ts
// Returns a Cypress chain that yields once the next render fires
Cypress.Commands.add('waitForGridRender', () => {
  cy.window().then(
    (win) =>
      new Cypress.Promise<void>((resolve) =>
        win.queryGrid('tbw-grid')!.addEventListener('render', () => resolve(), { once: true }),
      ),
  );
});

cy.get('[role="columnheader"]').contains('Salary').click();
cy.waitForGridRender();
```

#### WebdriverIO

```ts
async function waitForRender(): Promise<void> {
  await browser.executeAsync((done: () => void) => {
    window.queryGrid('tbw-grid')!.addEventListener('render', () => done(), { once: true });
  });
}

await $('[role="columnheader"]=Salary').click();
await waitForRender();
```

## Common operations

### Sort a column

#### Playwright

```ts
// Click the column header
await page.getByRole('columnheader', { name: 'Email' }).click();

// Assert sort direction via aria-sort (works even if you customised the icon)
await expect(page.getByRole('columnheader', { name: 'Email' })).toHaveAttribute(
  'aria-sort',
  'ascending',
);
```

#### Cypress

```ts
cy.contains('[role="columnheader"]', 'Email').click();
cy.contains('[role="columnheader"]', 'Email').should('have.attr', 'aria-sort', 'ascending');
```

#### WebdriverIO

```ts
await $('[role="columnheader"]=Email').click();
await expect($('[role="columnheader"]=Email')).toHaveAttribute('aria-sort', 'ascending');
```

### Read a cell's text content

#### Playwright

```ts
const cellAt = (row: number, field: string) =>
  page.locator(`tbw-grid .cell[data-row="${row}"][data-field="${field}"]`);

await expect(cellAt(0, 'name')).toHaveText('Alice');
```

#### Cypress

```ts
const cellAt = (row: number, field: string) =>
  cy.get(`tbw-grid .cell[data-row="${row}"][data-field="${field}"]`);

cellAt(0, 'name').should('have.text', 'Alice');
```

#### WebdriverIO

```ts
const cellAt = (row: number, field: string) =>
  $(`tbw-grid .cell[data-row="${row}"][data-field="${field}"]`);

await expect(cellAt(0, 'name')).toHaveText('Alice');
```

### Edit a cell

#### Playwright

```ts
const cell = page.locator('tbw-grid .cell[data-row="0"][data-field="email"]');

await cell.dblclick();                              // open the editor
await expect(cell).toHaveClass(/editing/);          // wait for editor to mount
await cell.locator('input').fill('alice@new.com');
await cell.locator('input').press('Enter');         // commit
await expect(cell).not.toHaveClass(/editing/);
await expect(cell).toHaveText('alice@new.com');
```

#### Cypress

```ts
cy.get('tbw-grid .cell[data-row="0"][data-field="email"]').as('cell');

cy.get('@cell').dblclick();
cy.get('@cell').should('have.class', 'editing');
cy.get('@cell').find('input').clear().type('alice@new.com{enter}');
cy.get('@cell').should('not.have.class', 'editing');
cy.get('@cell').should('have.text', 'alice@new.com');
```

#### WebdriverIO

```ts
const cell = await $('tbw-grid .cell[data-row="0"][data-field="email"]');

await cell.doubleClick();
await expect(cell).toHaveElementClass('editing');
const input = await cell.$('input');
await input.setValue('alice@new.com');
await browser.keys('Enter');
await expect(cell).not.toHaveElementClass('editing');
await expect(cell).toHaveText('alice@new.com');
```

### Select a row

#### Playwright

```ts
// Click the row's selection checkbox (the SelectionPlugin renders it in a __tbw_checkbox column)
await page
  .locator('tbw-grid .cell[data-row="0"][data-field="__tbw_checkbox"] input[type="checkbox"]')
  .check();

await expect(page.locator('tbw-grid .data-grid-row.selected')).toHaveCount(1);
await expect(page.locator('tbw-grid [role="row"][aria-selected="true"]')).toHaveCount(1);
```

#### Cypress

```ts
cy.get('tbw-grid .cell[data-row="0"][data-field="__tbw_checkbox"] input[type="checkbox"]').check();
cy.get('tbw-grid .data-grid-row.selected').should('have.length', 1);
```

#### WebdriverIO

```ts
await $('tbw-grid .cell[data-row="0"][data-field="__tbw_checkbox"] input[type="checkbox"]').click();
await expect($$('tbw-grid .data-grid-row.selected')).toBeElementsArrayOfSize(1);
```

### Assert the rendered row count

The grid is virtualized — `.data-grid-row` only matches **visible** rows. To assert against the full filtered dataset, read `grid.rows.length` instead of counting DOM elements.

#### Playwright

```ts
const visibleRows = await page.locator('tbw-grid .data-grid-row').count();
const totalRows = await page.evaluate(
  () => window.queryGrid('tbw-grid')!.rows.length,
);
expect(totalRows).toBe(100);
expect(visibleRows).toBeLessThanOrEqual(totalRows);
```

#### Cypress

```ts
cy.window().then((win) => {
  const grid = win.queryGrid('tbw-grid')!;
  expect(grid.rows.length).to.equal(100);
});
```

#### WebdriverIO

```ts
const totalRows = await browser.execute(
  () => window.queryGrid('tbw-grid')!.rows.length,
);
expect(totalRows).toEqual(100);
```

## The virtualization gotcha

At any moment the DOM only contains the rows in the viewport + a small overscan buffer. **If `data-row="500"` doesn't exist as a CSS match, the row hasn't been rendered yet — that's not a bug, that's virtualization working.** Bring it into view before interacting.

#### Playwright

```ts
// Scroll row 500 into view, then assert on it
await page.evaluate(
  ([rowIndex]) => {
    window.queryGrid('tbw-grid')!.scrollToRow(rowIndex);
  },
  [500],
);
await waitForRender(page);
await expect(page.locator('.cell[data-row="500"][data-field="name"]')).toBeVisible();
```

#### Cypress

```ts
cy.window().then((win) => {
  win.queryGrid('tbw-grid')!.scrollToRow(500);
});
cy.waitForGridRender();
cy.get('.cell[data-row="500"][data-field="name"]').should('be.visible');
```

#### WebdriverIO

```ts
await browser.execute((rowIndex: number) => {
  window.queryGrid('tbw-grid')!.scrollToRow(rowIndex);
}, 500);
await waitForRender();
await expect($('.cell[data-row="500"][data-field="name"]')).toBeDisplayed();
```

If your row has a stable business ID and you've configured [`getRowId`](/grid/api/core/interfaces/gridconfig.md#getrowid), use `scrollToRowById('emp-42')` instead — it survives sort and filter changes.

## Test against row identity, not row index

`data-row="0"` is "whatever happens to be the first visible row right now". After a sort it might be a different employee; after a filter it might be empty. For stable assertions, look up the cell **by the business value** instead:

#### Playwright

```ts
// "The row that contains 'Alice' in the name column"
const aliceRow = page.locator('tbw-grid .data-grid-row', {
  has: page.locator('.cell[data-field="name"]', { hasText: 'Alice' }),
});

await expect(aliceRow.locator('.cell[data-field="email"]')).toHaveText('alice@example.com');
```

#### Cypress

```ts
cy.get('tbw-grid .data-grid-row')
  .filter(':has(.cell[data-field="name"]:contains("Alice"))')
  .find('.cell[data-field="email"]')
  .should('have.text', 'alice@example.com');
```

#### WebdriverIO

```ts
const aliceRow = await $('tbw-grid .data-grid-row*=Alice');
await expect(aliceRow.$('.cell[data-field="email"]')).toHaveText('alice@example.com');
```

## Anti-patterns

- **`page.waitForTimeout(500)`** to "let the grid settle" — flake city. Always await `grid.ready()` or the next `'render'` event.
- **Counting `.data-grid-row` elements** as a proxy for total rows — virtualization makes this wrong by design. Read `grid.rows.length`.
- **Asserting on visual position** ("the third row from the top") — sorting and filtering invalidate this. Assert on data identity (the row that contains "Alice").
- **Querying by framework wrapper class names** (`._ng-content-c12`, React fiber IDs, Vue scoped attributes) — these change between builds. Stick to the grid's published classes and ARIA attributes.
- **Using `effectiveConfig` / internal APIs in test assertions** — these aren't covered by semver. Use `await grid.getConfig()` if you need to inspect resolved config.

## See also

  - [Troubleshooting → debug APIs](/grid/guides/troubleshooting.md#how-to-debug-the-grid): The manual / DevTools-console equivalent of this guide — same selectors, different audience
  - [Accessibility](/grid/guides/accessibility.md): The full ARIA contract — anything documented there is also a stable test selector
  - [GridSelectors API](/grid/api/core/variables/gridselectors/): Typed reference for every selector / class / data-attribute the grid publishes
  - [Multi-version coexistence](/grid/guides/multi-version.md): Testing apps that load more than one grid version on the same page

---

# Common Patterns

> Practical recipes for combining grid features. Covers data browsing, editable grids, master-detail, grouping, export, and more.

Real-world grids rarely use a single feature in isolation. This guide shows **tested combinations** that solve everyday requirements.

## Data Browsing & Selection

**Goal:** Let users sort, filter, and select rows from a large dataset.

#### Angular

```typescript
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import { GridMultiSortDirective } from '@toolbox-web/grid-angular/features/multi-sort';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, GridSelectionDirective, GridFilteringDirective, GridMultiSortDirective],
  template: `
    <tbw-grid
      [rows]="employees"
      [columns]="columns"
      selection="row"
      [filtering]="{ debounceMs: 200 }"
      multiSort
      (selection-change)="onSelectionChange()"
    />
  `,
})
export class EmployeeGridComponent {
  columns = [
    { field: 'id', header: 'ID', type: 'number', sortable: true },
    { field: 'name', header: 'Name', sortable: true, filterable: true },
    { field: 'department', header: 'Department', filterable: true },
    { field: 'salary', header: 'Salary', type: 'number', sortable: true },
  ];

  onSelectionChange() {
    // Access via ViewChild or queryGrid
  }
}
```

:::tip
Use `getSelectedRows()` instead of `getSelectedRowIndices()` — row objects are stable identifiers even after sorting and filtering.
:::

## Editable Grid with Undo

**Goal:** Inline cell editing with full undo/redo support.

#### Angular

```typescript
import { GridEditingDirective } from '@toolbox-web/grid-angular/features/editing';
import { GridUndoRedoDirective } from '@toolbox-web/grid-angular/features/undo-redo';
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, GridEditingDirective, GridUndoRedoDirective, GridSelectionDirective],
  template: `
    <tbw-grid
      [rows]="employees"
      [columns]="columns"
      editing="dblclick"
      dirtyTracking
      undoRedo
      selection="cell"
      [getRowId]="getRowId"
      (cell-commit)="onCellCommit($event)"
      (dirty-change)="onDirtyChange()"
    />
  `,
})
export class EditableGridComponent {
  columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name', editable: true },
    { field: 'email', header: 'Email', editable: true },
    { field: 'active', header: 'Active', type: 'boolean', editable: true },
  ];
  getRowId = (row: any) => row.id;

  onCellCommit(event: CustomEvent) {
    const { field, value } = event.detail;
    if (field === 'email' && !value.includes('@')) {
      event.preventDefault();
    }
  }

  onDirtyChange() {
    // Access editing plugin for dirty rows
  }
}
```

:::tip
When using the features API, plugin dependencies are resolved automatically — no need to worry about ordering.
If using the advanced plugins API directly, `EditingPlugin` must be loaded **before** `UndoRedoPlugin`.
:::

## Grouped Data with Aggregates

**Goal:** Group rows by a field and show aggregated values (sum, average, count).

#### Angular

```typescript
import { GridGroupingRowsDirective } from '@toolbox-web/grid-angular/features/grouping-rows';
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, GridGroupingRowsDirective, GridSelectionDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [groupingRows]="groupingRows"
      [selection]="{ mode: 'row' }"
    />
  `,
})
export class DepartmentGridComponent {
  groupingRows = {
    groupOn: (row: any) => [row.department],
    defaultExpanded: true,
    aggregators: { salary: 'avg', id: 'count' },
  };
  columns = [
    { field: 'department', header: 'Department' },
    { field: 'name', header: 'Name' },
    {
      field: 'salary', header: 'Salary', type: 'number',
      format: (value: number) => `$${value.toLocaleString()}`,
    },
    { field: 'id', header: 'Count', type: 'number' },
  ];
}
```

## Export Selected Rows

**Goal:** Let users filter data, select a subset, and export it.

#### Angular

```typescript
import { GridExportDirective } from '@toolbox-web/grid-angular/features/export';
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import { Component, ViewChild, ElementRef } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, GridExportDirective, GridSelectionDirective, GridFilteringDirective],
  template: `
    <button (click)="handleExport()">Export CSV</button>
    <tbw-grid #grid [rows]="employees" [columns]="columns" selection="row" filtering export />
  `,
})
export class ExportableGridComponent {
  @ViewChild('grid') gridEl!: ElementRef;
  columns = [
    { field: 'name', header: 'Name', filterable: true },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department', filterable: true },
  ];

  handleExport() {
    this.gridEl.nativeElement.getPluginByName('export')?.exportCsv({ fileName: 'employees' });
  }
}
```

## Master-Detail

**Goal:** Expand a row to show related detail records.

#### Angular

```typescript
import { GridDetailView } from '@toolbox-web/grid-angular/features/master-detail';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, GridDetailView],
  template: `
    <tbw-grid [rows]="orders" [columns]="columns">
      <tbw-grid-detail>
        <ng-template let-row>
          <div style="padding: 1rem">
            <strong>Order #{{ row.orderId }}</strong>
            <tbw-grid [rows]="row.items" [columns]="itemColumns"
                      style="height: 200px; display: block">
            </tbw-grid>
          </div>
        </ng-template>
      </tbw-grid-detail>
    </tbw-grid>
  `,
})
export class OrderGridComponent {
  columns = [
    { field: 'orderId', header: 'Order', type: 'number' },
    { field: 'customer', header: 'Customer' },
    { field: 'total', header: 'Total', type: 'number' },
  ];
  itemColumns = [
    { field: 'item', header: 'Item' },
    { field: 'qty', header: 'Qty', type: 'number' },
    { field: 'price', header: 'Price', type: 'number' },
  ];
}
```

## High-Volume Data

**Goal:** Handle 10k+ rows with pinned identifier columns and column virtualization.

#### Angular

```typescript
import { GridPinnedColumnsDirective } from '@toolbox-web/grid-angular/features/pinned-columns';
import { GridColumnVirtualizationDirective } from '@toolbox-web/grid-angular/features/column-virtualization';
import { GridMultiSortDirective } from '@toolbox-web/grid-angular/features/multi-sort';
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, GridPinnedColumnsDirective, GridColumnVirtualizationDirective, GridMultiSortDirective, GridFilteringDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      pinnedColumns
      columnVirtualization
      multiSort
      [filtering]="{ debounceMs: 300 }"
      fitMode="fixed"
    />
  `,
})
export class LargeDataGridComponent {
  columns = [
    { field: 'id', header: 'ID', type: 'number', pinned: 'left', width: 80 },
    { field: 'name', header: 'Name', pinned: 'left', width: 180 },
    // ... many more columns
  ];
}
```

:::tip
For datasets over 50k rows, consider `ServerSidePlugin` to paginate and filter on the server instead of loading all data upfront.
:::

---

## Real-Time / Streaming Data

**Goal:** Push live updates from a WebSocket, SSE, or polling source into the grid efficiently.

Use `applyTransaction()` to batch add, update, and remove operations into a single render cycle.
For high-frequency streams (many messages per second), `applyTransactionAsync()` automatically
merges all calls within one animation frame.

```typescript
import { createGrid } from '@toolbox-web/grid';
import type { RowTransaction } from '@toolbox-web/grid';

const grid = createGrid<Trade>('#my-grid');

// --- Low-to-moderate frequency: applyTransaction ---
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  grid.applyTransaction({
    add:    msg.type === 'add'    ? [msg.row]                               : undefined,
    update: msg.type === 'update' ? [{ id: msg.id, changes: msg.changes }]  : undefined,
    remove: msg.type === 'remove' ? [{ id: msg.id }]                        : undefined,
  });
};

// --- High frequency: applyTransactionAsync ---
// Merges rapid calls within a single animation frame
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  grid.applyTransactionAsync({
    update: [{ id: msg.id, changes: msg.changes }],
  });
};
```

### Transaction shape

```typescript
interface RowTransaction<T> {
  add?:    T[];                           // Appended to the end
  update?: { id: string; changes: Partial<T> }[];  // In-place mutation by row ID
  remove?: { id: string }[];              // Removed by row ID
}
```

Operations are applied in order: **removes → updates → adds**. This ensures updates don't target
rows about to be removed, and new rows don't collide with existing IDs.

### Choosing between sync and async

| Scenario | Method | Animations |
|----------|--------|------------|
| User action, moderate stream (< 10 msg/s) | `applyTransaction()` | Yes (configurable) |
| High-frequency ticker (100+ msg/s) | `applyTransactionAsync()` | Disabled (batched) |

:::tip
Both methods return a `TransactionResult` with the actual `added`, `updated`, and `removed` row objects — useful for logging or post-processing.
:::

## Event Handling Recipes

Practical patterns for wiring grid events into your application — listening across frameworks, reacting to scroll, and acting after a render flush.

### Listening to Events Across Frameworks

The grid dispatches standard `CustomEvent`s that bubble up the DOM. All events use `bubbles: true` and `composed: true`. Cancelable events (`cell-commit`, `row-commit`, `column-move`, `row-move`) honour `preventDefault()` to reject the action — see the [Cancelable Events table](/grid/api-reference.md#cancelable-events).

#### Angular

```typescript
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { CellClickDetail, CellCommitDetail } from '@toolbox-web/grid';

@Component({
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="employees"
      (cellClick)="onCellClick($event)"
      (cellCommit)="onCellCommit($event)"
    />
  `,
})
export class EmployeeGridComponent {
  onCellClick(detail: CellClickDetail<Employee>) {
    console.log(detail.row, detail.field);
  }

  onCellCommit(detail: CellCommitDetail<Employee>) {
    if (!isValid(detail.value)) {
      // To cancel, use the native event via kebab-case binding:
      // (cell-commit)="onCellCommit($event)" → event.preventDefault()
    }
  }
}
```

:::note[camelCase vs kebab-case]
Use **camelCase** outputs like `(cellClick)` for typed, unwrapped detail. Use kebab-case `(cell-commit)` when you need `preventDefault()` on the native `CustomEvent`.
:::

### Scroll-Driven Patterns (`tbw-scroll`)

`tbw-scroll` fires (rAF-batched) whenever the grid's vertical viewport scrolls. The detail payload contains `scrollTop`, `scrollHeight`, `clientHeight`, and a `direction: 'vertical'` discriminator (reserved for future horizontal opt-in). The detail is a fresh object literal each tick — safe to retain, freeze, copy into framework state, or post to a worker.

:::tip[Server-side pagination?]
For paginated server-side data, prefer the [`ServerSidePlugin`](/grid/plugins/server-side.md) — it handles block fetching out of the box. `tbw-scroll` is the lower-level primitive for cases the plugin doesn't cover (custom load-more triggers, deferred cell content, scroll-driven UI, etc.).
:::

#### Infinite scroll / load more

```typescript
grid.on('tbw-scroll', ({ scrollTop, scrollHeight, clientHeight }) => {
  if (scrollTop + clientHeight >= scrollHeight - 200) {
    loadNextPage();
  }
});
```

#### Sticky scroll-progress indicator

A toolbar or progress bar that lives outside the grid and tracks scroll position:

```typescript
grid.on('tbw-scroll', ({ scrollTop, scrollHeight, clientHeight }) => {
  const max = scrollHeight - clientHeight;
  const pct = max > 0 ? scrollTop / max : 0;
  progressBarEl.style.width = `${pct * 100}%`;
});
```

For purely visual scroll-driven CSS effects on a different scroller, also consider the native `animation-timeline: scroll()` — no JS needed.

#### Defer heavy cell content (Angular `@defer` style)

Render expensive content (charts, images, embedded video) only when its row is near the viewport:

```typescript
grid.on('tbw-scroll', ({ scrollTop, clientHeight }) => {
  // Lazy-mount components in the visible window
  hydrateHeavyCellsBetween(scrollTop, scrollTop + clientHeight);
});
```

#### Dismiss overlays on scroll

Tooltips, popovers, context menus rendered outside the grid should typically close when the user scrolls:

```typescript
grid.on('tbw-scroll', () => closeOpenOverlays());
```

:::note[Not for per-row visibility tracking]
`tbw-scroll` fires at most once per frame, **not** per row entering or leaving the viewport. For "row N just became visible" semantics, observe rendered row elements directly in `afterRowRender` or use `IntersectionObserver` from a custom plugin.
:::

**Framework adapter names** — disambiguated to avoid colliding with native scroll events:

| Adapter | Binding |
|---------|---------|
| React | `<DataGrid onTbwScroll={...} />` |
| Vue | `<TbwGrid @tbw-scroll="..." />` |
| Angular | `<tbw-grid (tbwScroll)="..." />` |

### Render-Completed Patterns (`render`)

The `render` event fires once at the end of every render cycle (the single RAF flush in the render scheduler), **after** all plugin `afterRender` hooks have run and **after** `grid.ready()` has resolved. Use this when you need to act on the rendered DOM immediately after a programmatic mutation — without resorting to `setTimeout` or double-`requestAnimationFrame` hacks.

:::tip[`ready()` vs `render` event]
`grid.ready()` resolves **once**, after the first render. The `render` event fires on **every** flush. When you only care about a specific mutation (e.g. the row you just added), attach with `{ once: true }`.
:::

The detail payload includes the highest render phase that ran (`phase`), whether this was the first render (`initial`), the post-`processRows` row count (`rowCount`), and the current virtual window (`visibleRange`, or `null` when virtualization is disabled).

#### Focus the first input after `addRow` in full-grid edit mode

The original motivation: with `editing: { mode: 'grid' }` every row is permanently in edit mode. After inserting a new row you want the first cell's input focused — but the row doesn't exist in the DOM until the next render.

```typescript
function addEmployee() {
  grid.addRow({ id: crypto.randomUUID(), name: '', email: '' });
  grid.addEventListener(
    'render',
    () => {
      const input = grid.querySelector<HTMLInputElement>(
        '[data-row="0"][data-col="0"] input',
      );
      input?.focus();
    },
    { once: true },
  );
}
```

#### Skip cheap scroll renders

The event fires on virtualization-only re-renders too. If you only care about row/column model changes, gate on `phase`:

```typescript
import { RenderPhase } from '@toolbox-web/grid';

grid.on('render', ({ phase, rowCount }) => {
  if (phase < RenderPhase.ROWS) return; // ignore scroll/style-only flushes
  statusBar.textContent = `${rowCount} rows rendered`;
});
```

**Framework adapter names**:

| Adapter | Binding |
|---------|---------|
| React | `<DataGrid onRender={...} />` |
| Vue | `<TbwGrid @render="..." />` |
| Angular | `<tbw-grid (render)="..." />` |

## See Also

  - [Plugins Overview](/grid/plugins.md): Browse all 23 plugins
  - [Events Reference](/grid/api-reference.md#events): Complete event catalog for all plugins
  - [Performance](/grid/guides/performance.md): Virtualization, benchmarks, and optimization tips
  - [API Reference](/grid/api-reference.md): Full property and method reference

---

# Migrating from v1 to v2

> Complete migration guide for upgrading @toolbox-web/grid and its framework adapters from v1 to v2.

This guide covers every breaking change in `@toolbox-web/grid` v2 and its Angular, React, and Vue adapters. Most changes are simple renames that can be done with find-and-replace. A handful require manual migration due to structural API changes.

## Quick Summary

v2 removes **~106 deprecated items** across the grid core and all three framework adapters. The majority are renames — removing framework prefixes from types (e.g., `ReactGridConfig` → `GridConfig`), renaming features for clarity (e.g., `sorting` → `multiSort`), and replacing `sticky` with `pinned`. A few structural API changes (like `useGridEvent()` removal) require manual attention.

:::note
  **Most of these APIs have been deprecated for a long time.** The earliest deprecations date back to v1.0.0, and the most recent batch was introduced in v1.24.0+. If you've been following deprecation warnings in your IDE and keeping your code up to date, you may have very little (or nothing) to change. The tables below include a "Deprecated since" column so you can quickly check whether a removal affects your version.
:::

:::tip
  Run `git diff` after each section to verify changes before committing.
:::

## Automated Find-and-Replace

~75 of ~106 changes are simple 1:1 renames. Use your IDE's find-and-replace (Ctrl+Shift+H) or the `sed` commands below.

:::caution
  **Order matters** for some replacements. Replace `rowReorder` before `reorder`, and `row-reorder` before `reorder` in import paths, to avoid creating incorrect names like `reorderColumnsRows`.
:::

### Grid Core — Type & Event Renames

| v1 (removed)             | v2 (replacement)         | Kind     | Deprecated since |
| ------------------------ | ------------------------ | -------- | ---------------- |
| `ActivateCellDetail`     | `CellActivateDetail`     | Type     | v1.0.0           |
| `activate-cell`          | `cell-activate`          | Event    | v1.0.0           |
| `StickyPosition`         | `PinnedPosition`         | Type     | v1.15.0          |
| `ResolvedStickyPosition` | `ResolvedPinnedPosition` | Type     | v1.15.0          |
| `EditorContext`           | `ColumnEditorContext`     | Type     | v1.12.0          |
| `RowGroupingConfig`      | `GroupingRowsConfig`     | Type     | v1.24.0          |
| `RowGroupingState`       | `GroupingRowsState`      | Type     | v1.24.0          |
| `PLUGIN_QUERIES`         | String literals with `grid.query()` | Constant | v1.8.0 |

### Grid Core — Property & Attribute Renames

| v1 (removed)   | v2 (replacement) | Kind                 | Deprecated since |
| -------------- | ---------------- | -------------------- | ---------------- |
| `.sticky`      | `.pinned`        | Column config property | v1.15.0        |
| `'sticky'`     | `'pinned'`       | String key           | v1.15.0          |
| `sticky:`      | `pinned:`        | Config key           | v1.15.0          |
| `sizable`      | `resizable`      | HTML attribute       | v1.0.0           |

### Server-Side Plugin — DataSource Renames

The server-side plugin's datasource interface was renamed from row-centric to node-centric terminology (a "node" is the atomic pagination unit — a row for flat data, a top-level tree/group node for hierarchical data).

| v1 (removed)                       | v2 (replacement)                    | Kind                  | Deprecated since |
| ---------------------------------- | ----------------------------------- | --------------------- | ---------------- |
| `GetRowsParams.startRow`           | `GetRowsParams.startNode`           | Interface property    | v1.24.0          |
| `GetRowsParams.endRow`             | `GetRowsParams.endNode`             | Interface property    | v1.24.0          |
| `GetRowsResult.totalRowCount`      | `GetRowsResult.totalNodeCount`      | Interface property    | v1.24.0          |
| `GetRowsResult.lastRow`            | `GetRowsResult.lastNode`            | Interface property    | v1.24.0          |
| `plugin.getTotalRowCount()`        | `plugin.getTotalNodeCount()`        | Method                | v1.24.0          |
| `plugin.isRowLoaded(index)`        | `plugin.isNodeLoaded(index)`        | Method                | v1.24.0          |

### Grid Core — Feature Alias Renames

| v1 (removed)   | v2 (replacement)   | Kind         | Deprecated since |
| -------------- | ------------------ | ------------ | ---------------- |
| `'sorting'`    | `'multiSort'`      | Feature name | v1.24.0          |
| `sorting:`     | `multiSort:`       | Config key   | v1.24.0          |
| `'reorder'`    | `'reorderColumns'` | Feature name | v1.24.0          |
| `reorder:`     | `reorderColumns:`  | Config key   | v1.24.0          |
| `rowReorder`   | `reorderRows`      | Feature name | v1.24.0          |

### Grid Core — Function Renames (Plugin Authors)

| v1 (removed)               | v2 (replacement)       | Kind        | Deprecated since |
| -------------------------- | ---------------------- | ----------- | ---------------- |
| `onPluginQuery`            | `handleQuery`          | Plugin hook | v1.8.0           |
| `getPivotAggregator`       | `getValueAggregator`   | Function    | v1.24.0          |
| `createPinnedRowsElement`  | `createInfoBarElement` | Function    | v1.24.0          |

### Angular Adapter

| v1 (removed)          | v2 (replacement)   | Kind                 | Deprecated since |
| --------------------- | ------------------ | -------------------- | ---------------- |
| `AngularGridAdapter`  | `GridAdapter`      | Type / export        | 0.11.0           |
| `AngularCellRenderer` | `CellRenderer`     | Type                 | 0.11.0           |
| `AngularCellEditor`   | `CellEditor`       | Type                 | 0.11.0           |
| `AngularColumnConfig` | `ColumnConfig`     | Type                 | 0.11.0           |
| `AngularGridConfig`   | `GridConfig`       | Type                 | 0.11.0           |
| `AngularTypeDefault`  | `TypeDefault`      | Type                 | 0.11.0           |
| `[angularConfig]`     | `[gridConfig]`     | Directive input      | 0.11.0           |
| `[sorting]`           | `[multiSort]`      | Directive input      | 0.11.0           |
| `[reorder]`           | `[reorderColumns]` | Directive input      | 0.11.0           |
| `[rowReorder]`        | `[reorderRows]`    | Directive input      | 0.11.0           |
| `TbwCellEditor`       | `TbwEditor`        | Structural directive | 0.11.0           |
| `TbwCellView`         | `TbwRenderer`      | Structural directive | 0.11.0           |

**Feature import paths:**

| v1 path                                          | v2 path                                                |
| ------------------------------------------------ | ------------------------------------------------------ |
| `@toolbox-web/grid-angular/features/sorting`     | `@toolbox-web/grid-angular/features/multi-sort`        |
| `@toolbox-web/grid-angular/features/reorder`     | `@toolbox-web/grid-angular/features/reorder-columns`   |
| `@toolbox-web/grid-angular/features/row-reorder` | `@toolbox-web/grid-angular/features/reorder-rows`      |

### React Adapter

| v1 (removed)                          | v2 (replacement)               | Kind           | Deprecated since |
| ------------------------------------- | ------------------------------ | -------------- | ---------------- |
| `ReactGridAdapter`                    | `GridAdapter`                  | Type / export  | 0.11.0           |
| `ReactColumnConfig`                   | `ColumnConfig`                 | Type           | 0.11.0           |
| `ReactGridConfig`                     | `GridConfig`                   | Type           | 0.11.0           |
| `ReactTypeDefault`                    | `TypeDefault`                  | Type           | 0.11.0           |
| `reactTypeDefaultToGridTypeDefault`   | `typeDefaultToBaseTypeDefault` | Function       | 0.11.0           |
| `processReactGridConfig`              | `processGridConfig`            | Function       | 0.11.0           |
| `sorting` prop                        | `multiSort` prop               | Component prop | 0.11.0           |
| `reorder` prop                        | `reorderColumns` prop          | Component prop | 0.11.0           |
| `rowReorder` prop                     | `reorderRows` prop             | Component prop | 0.11.0           |

**Feature import paths:**

| v1 path                                      | v2 path                                            |
| -------------------------------------------- | -------------------------------------------------- |
| `@toolbox-web/grid-react/features/sorting`     | `@toolbox-web/grid-react/features/multi-sort`      |
| `@toolbox-web/grid-react/features/reorder`     | `@toolbox-web/grid-react/features/reorder-columns` |
| `@toolbox-web/grid-react/features/row-reorder` | `@toolbox-web/grid-react/features/reorder-rows`    |

### Vue Adapter

| v1 (removed)      | v2 (replacement)      | Kind           | Deprecated since |
| ----------------- | --------------------- | -------------- | ---------------- |
| `VueGridAdapter`  | `GridAdapter`         | Type / export  | 0.11.0           |
| `VueCellRenderer` | `CellRenderer`        | Type           | 0.11.0           |
| `VueCellEditor`   | `CellEditor`          | Type           | 0.11.0           |
| `VueColumnConfig` | `ColumnConfig`        | Type           | 0.11.0           |
| `VueGridConfig`   | `GridConfig`          | Type           | 0.11.0           |
| `VueTypeDefault`  | `TypeDefault`         | Type           | 0.11.0           |
| `sorting` prop    | `multiSort` prop      | Component prop | 0.11.0           |
| `reorder` prop    | `reorderColumns` prop | Component prop | 0.11.0           |
| `rowReorder` prop | `reorderRows` prop    | Component prop | 0.11.0           |

**Feature import paths:**

| v1 path                                    | v2 path                                          |
| ------------------------------------------ | ------------------------------------------------ |
| `@toolbox-web/grid-vue/features/reorder`     | `@toolbox-web/grid-vue/features/reorder-columns` |
| `@toolbox-web/grid-vue/features/row-reorder` | `@toolbox-web/grid-vue/features/reorder-rows`    |

### CSS Default Export

```typescript
// v1
import styles from '@toolbox-web/grid/styles';

// v2
import { gridStyles } from '@toolbox-web/grid/styles';
```

---

## Manual Migration Required

These structural API changes cannot be safely automated with find-and-replace. Each requires understanding the surrounding code.

### `queryPlugins()` → `query()` — Parameter format change

*Deprecated since v1.8.0.* The object-based parameter was replaced with a flat signature.

#### v1 (removed)

    ```typescript
    const results = grid.queryPlugins<boolean>({
      type: 'canMoveColumn',
      context: column,
    });
    ```

#### v2

    ```typescript
    const results = grid.query<boolean>('canMoveColumn', column);
    ```

### `suspendProcessing()` — Removed entirely

*Deprecated since v1.21.0.* This method was already a no-op in late v1. Delete all calls to `suspendProcessing()` and `resumeProcessing()`. Use `insertRow()` / `removeRow()` for individual row mutations — batching is handled internally.

#### v1 (removed)

    ```typescript
    grid.suspendProcessing();
    // ... batch operations ...
    grid.resumeProcessing();
    ```

#### v2

    ```typescript
    // Just use row mutation methods directly
    grid.insertRow(newRow, index);
    grid.removeRow(rowId);
    ```

### `getExtraHeight()` / `getExtraHeightBefore()` → `getRowHeight()`

*Plugin authors only. Deprecated since v1.12.0.* The two aggregate height hooks were replaced by a single per-row hook.

#### v1 (removed)

    ```typescript
    getExtraHeight(): number {
      return this.expandedRows.size * this.detailHeight;
    }

    getExtraHeightBefore(beforeRowIndex: number): number {
      let height = 0;
      for (const idx of this.expandedRowIndices) {
        if (idx < beforeRowIndex) height += this.detailHeight;
      }
      return height;
    }
    ```

#### v2

    ```typescript
    getRowHeight(row: unknown, index: number): number | undefined {
      if (this.isExpanded(row)) {
        return this.baseRowHeight + this.getDetailHeight(row);
      }
      return undefined; // use default height
    }
    ```

### `resolveIcon()` → `setIcon()`

*Plugin authors only. Deprecated since v1.31.0.* The return-value pattern was replaced with a DOM-mutation pattern.

#### v1 (removed)

    ```typescript
    const icon = this.resolveIcon('sort-asc');
    element.innerHTML = typeof icon === 'string' ? icon : '';
    ```

#### v2

    ```typescript
    this.setIcon(element, 'sort-asc');
    ```

### `PLUGIN_QUERIES` constant → String literals

*Plugin authors only. Deprecated since v1.8.0.* The constant object was removed. Use string literals with `grid.query()` instead.

#### v1 (removed)

    ```typescript
    import { PLUGIN_QUERIES } from '@toolbox-web/grid';

    grid.queryPlugins({
      type: PLUGIN_QUERIES.CAN_MOVE_COLUMN,
      context: column,
    });
    ```

#### v2

    ```typescript
    grid.query<boolean>('canMoveColumn', column);
    ```

### Angular: `commit`/`cancel` outputs → `onCommit`/`onCancel` callbacks

*Deprecated since grid-angular 0.11.0.* The `EventEmitter`-based outputs on the editor directive were replaced with simple callback functions on the editor context.

#### v1 (removed)

    ```typescript
    // In your editor component
    @Output() commit = new EventEmitter<string>();
    @Output() cancel = new EventEmitter<void>();

    save() {
      this.commit.emit(this.value);
    }
    ```

#### v2

    ```typescript
    // Editor context provides callbacks directly
    save() {
      this.context.onCommit(this.value);
    }

    discard() {
      this.context.onCancel();
    }
    ```

### React: `useGridEvent()` → Event props on `<DataGrid>`

*Deprecated since grid-react 0.18.0.* The `useGridEvent` hook was removed. Use event handler props directly on the `<DataGrid>` component.

#### v1 (removed)

    ```tsx
    import { useGridEvent } from '@toolbox-web/grid-react';

    function MyGrid() {
      const gridRef = useRef(null);
      useGridEvent(gridRef, 'selection-change', (e) => {
        setSelected(e.detail);
      });

      return <DataGrid ref={gridRef} />;
    }
    ```

#### v2

    ```tsx
    function MyGrid() {
      return (
        <DataGrid
          onSelectionChange={(e) => setSelected(e.detail)}
        />
      );
    }
    ```

### Vue: `useGridEvent()` → Template event handlers

*Deprecated since grid-vue 0.11.0.* The `useGridEvent` composable was removed. Use standard Vue template event handlers on `<TbwGrid>`.

#### v1 (removed)

    ```vue
    <script setup>
    import { useGridEvent } from '@toolbox-web/grid-vue';

    useGridEvent('selection-change', (e) => {
      selected.value = e.detail;
    });
    </script>

    <template>
      <TbwGrid />
    </template>
    ```

#### v2

    ```vue
    <template>
      <TbwGrid @selection-change="onSelectionChange" />
    </template>

    <script setup>
    function onSelectionChange(e) {
      selected.value = e.detail;
    }
    </script>
    ```

### All Adapters: `SelectionMethods`/`ExportMethods` → Feature-specific functions

*Deprecated since adapter 0.11.0.* The monolithic `injectGrid()` / `useGrid()` return type no longer includes selection and export methods. Import them from their respective feature modules instead.

#### Angular

    ```typescript
    // v1
    const { selectAll, clearSelection, exportToCsv } = injectGrid();

    // v2
    import { injectGridSelection } from '@toolbox-web/grid-angular/features/selection';
    import { injectGridExport } from '@toolbox-web/grid-angular/features/export';

    const { selectAll, clearSelection } = injectGridSelection();
    const { exportToCsv } = injectGridExport();
    ```

---

## FAQ

### Can I use v1 plugins with v2?

Yes, as long as they use `handleQuery()` (not `onPluginQuery()`). If your plugin implements `onPluginQuery`, rename it to `handleQuery` — the signature is identical.

### Do I need to update adapter packages at the same time?

Yes. The v2 adapter packages (`@toolbox-web/grid-angular`, `@toolbox-web/grid-react`, `@toolbox-web/grid-vue`) require `@toolbox-web/grid` v2 as a peer dependency. Update all packages together.

### What about the `default` CSS export?

The default export from the styles module was removed. Use the named export instead:

```typescript
// v1
import styles from '@toolbox-web/grid/styles';

// v2
import { gridStyles } from '@toolbox-web/grid/styles';
```

### Are there any runtime behavior changes?

The `suspendProcessing()` method was already a no-op in late v1 — removing it has no runtime impact. All other changes are API surface renames. If your v1 code compiled without deprecation warnings, the migration is purely mechanical.

---

# Multi-version coexistence

> How @toolbox-web/grid lets two different grid versions live on one page — useful for micro-frontends and gradual upgrades.

This guide is **framework-agnostic**. Multi-version coexistence is a property of the underlying web component (`<tbw-grid>` and its custom-element registry), not of any adapter — it applies equally to vanilla JavaScript, Module Federation, [Native Federation](https://github.com/angular-architects/module-federation-plugin/blob/main/libs/native-federation/README.md), iframe-less micro-frontend shells, and any setup where two copies of `@toolbox-web/grid` end up on the same page. You don't need a framework adapter, and you don't need to install anything extra.

When two micro-frontends on the same page each ship their own copy of
`@toolbox-web/grid` (for example, a host app on `v2.14` while a widget is
still on `v2.11`), the browser's custom-elements registry is shared and
first-wins: a second `customElements.define('tbw-grid', …)` call throws.
Starting with `v2.14`, the grid handles this for you automatically — the
second bundle to load registers itself under a version-suffixed tag and the
two implementations coexist.

## How it works

Each grid bundle exposes the version it was built with on the class:

```ts
import { DataGridElement } from '@toolbox-web/grid';

DataGridElement.version;   // e.g. '2.14.0' — set at build time
DataGridElement.tagName;   // 'tbw-grid' — the canonical tag
DataGridElement.activeTag; // 'tbw-grid' OR 'tbw-grid-v<sanitised-version>'
```

At module load the bundle calls `customElements.define()` using the
following rule:

1. **No existing registration** → register under `tbw-grid`. The bundle owns
   the bare tag. `activeTag === 'tbw-grid'`.
2. **An existing registration at the SAME version** → don't re-register;
   reuse the existing class. `activeTag === 'tbw-grid'`.
3. **An existing registration at a DIFFERENT version** → register under
   `tbw-grid-v<sanitised-version>` (e.g. `tbw-grid-v2-14-0`). `activeTag`
   reflects the suffixed tag.

The sanitiser replaces every non-alphanumeric character with `-` and
lower-cases the result, so semver pre-release / build-metadata strings like
`2.14.0-beta.1+build.42` produce `tbw-grid-v2-14-0-beta-1-build-42`.

In the **single-version** case (99% of apps), nothing changes: the tag is
`<tbw-grid>` and existing markup, styles, and tooling continue to work
unmodified.

## The `data-tbw-grid` selector contract

Because the tag name is no longer guaranteed to be `tbw-grid` literally,
every grid sets a stable attribute on its host element when it connects:

```html
<tbw-grid data-tbw-grid="">…</tbw-grid>
<tbw-grid-v2-14-0 data-tbw-grid="">…</tbw-grid-v2-14-0>
```

**Always use `[data-tbw-grid]` (not the tag name) when you need to target
"any grid" in CSS, querySelector, or `closest()`**. The framework adapters
(`@toolbox-web/grid-react`, `@toolbox-web/grid-vue`,
`@toolbox-web/grid-angular`) already do this internally — your application
code only needs to follow the same rule for hand-written selectors:

```css
/* ✅ Works for both bare and suffixed grids */
[data-tbw-grid] { font-size: 14px; }

/* ⚠️ Only matches the first-loaded bundle's bare tag */
tbw-grid { font-size: 14px; }
```

The bundled themes (`@toolbox-web/grid/themes/dg-theme-*.css`) already use
`[data-tbw-grid]` for their root selectors, so they apply correctly to every
loaded version. If you author a custom theme, follow the same pattern.

## Adapter usage

The React and Vue adapters resolve `activeTag` at render time, so they
always emit the correct tag for the bundle they imported:

```tsx
// React — renders <tbw-grid> or <tbw-grid-v…> depending on which bundle
// supplied DataGridElement.
import { DataGrid } from '@toolbox-web/grid-react';
```

```vue
<!-- Vue — same behaviour via <component :is="…"> internally. -->
<TbwGrid :rows="rows" :columns="columns" />
```

The Angular adapter's `Grid` directive matches both the bare `tbw-grid` tag
**and** the stable `[data-tbw-grid]` attribute, and its shell-content
directives (`tbw-grid-header-content`, `tbw-grid-toolbar-content`) locate their
host via `closest('[data-tbw-grid]')`. In single-version setups embed
`<tbw-grid>` literally as before. For multi-version Angular usage, render the
active tag for the bundle you imported and add `data-tbw-grid` so the directive
attaches (Angular matches selectors at compile time, so the runtime tag can't be
matched by name alone):

```html
<!-- activeTag for this bundle is e.g. 'tbw-grid-v2-15-0' -->
<tbw-grid-v2-15-0 data-tbw-grid [rows]="rows" [gridConfig]="config">
  <tbw-grid-header-content [order]="0">
    <ng-template let-grid>…</ng-template>
  </tbw-grid-header-content>
</tbw-grid-v2-15-0>
```

## Per-bundle styles

The internal style injector scopes its `<style id="tbw-grid-styles-…">`
element to the active tag, and rewrites bare `tbw-grid` selectors in the
injected CSS to the active tag. Each bundle ships its own stylesheet
without overwriting the other.

## Imperative helpers

The `createGrid()` and `queryGrid()` helpers from `@toolbox-web/grid` resolve
`DataGridElement.activeTag` internally, so they operate on the tag owned by the
bundle that exported them:

```ts
import { createGrid, queryGrid } from '@toolbox-web/grid';

// Creates <tbw-grid> or <tbw-grid-v…> depending on which bundle you imported.
const grid = createGrid({ columns: [{ field: 'name' }] });

// `awaitUpgrade` waits for the active tag's upgrade, not the bare tag.
const found = await queryGrid('[data-tbw-grid]', true);
```

When you query with a hand-written selector, prefer `[data-tbw-grid]` over
`tbw-grid` so it matches a suffixed grid too.

## The `globalThis.DataGridElement` alias

For convenience the grid exposes its class on `globalThis.DataGridElement`,
but this alias is **first-wins** and points at the first-loaded bundle's
class. Multi-version-aware code that needs a specific version's class must

or look it up via `customElements.get(activeTag)`. Don't rely on the global
when multiple bundles may be present.

---

# Performance

> Optimize @toolbox-web/grid for large datasets — virtualization tuning, bundle optimization, rendering best practices, and benchmarks.

`@toolbox-web/grid` is engineered for high performance out of the box. This guide helps you understand the performance characteristics and tune the grid for your specific workload.

:::tip[Looking for benchmarks?]
We publish a head-to-head benchmark against AG Grid, Tabulator, and SlickGrid that **runs live in your browser** — render 1k / 10k / 100k rows side-by-side and watch the numbers. See [Compared to other grids](/grid/comparison.md) for the methodology, results, and a feature matrix.
:::

## Why it's fast

A short explanation lives here so you don't have to dig — for the full architectural narrative (render scheduler, virtualization, DOM recycling, template cloning, faux scrollbar) see the [Architecture deep-dive](/grid/architecture.md).

| Technique | What it buys you |
|---|---|
| **Centralized render scheduler** | All updates coalesce into a single `requestAnimationFrame` — no layout thrashing, no double work |
| **Row + column virtualization** | Rendering 100k rows costs the same as rendering 50 |
| **DOM recycling with epoch invalidation** | Row elements are reused via a pool — minimal GC, no element churn |
| **Template cloning** (`cloneNode(true)`) | 3-4× faster than `createElement` + attribute assignment |
| **Event delegation** | One listener per event type on the container — scales to any dataset |
| **Faux scrollbar** | Scroll container is separate from the rendered content — zero reflow on scroll |
| **Phase-priority execution** | Highest-priority phase wins per frame — full re-renders absorb sub-renders |

## Key Performance Features

### Row Virtualization

The grid only renders rows visible in the viewport plus a configurable overscan buffer. This means rendering 100,000 rows is as fast as rendering 50 rows.

```typescript
grid.gridConfig = {
  columns: [...],
  rowHeight: 28,   // Fixed row height in pixels (default: auto-measured)
};
```

- **Default row height:** Auto-measured from first row (respects `--tbw-row-height` CSS variable)
- **Variable row heights:** Supported via `rowHeight: (row, index) => number | undefined`

### Column Virtualization

For grids with many columns (50+), enable column virtualization:

```typescript
import '@toolbox-web/grid/features/column-virtualization';

grid.gridConfig = {
  columns: manyColumns,
  features: { columnVirtualization: true },
};
```

### Render Scheduler

All rendering is batched through a centralized `RenderScheduler` that coalesces multiple update requests into a single `requestAnimationFrame` callback.

**Render phases (lowest → highest priority):**

| Phase | Priority | What It Does |
|-------|----------|-------------|
| STYLE | 1 | CSS custom property updates |
| VIRTUALIZATION | 2 | Scroll position + visible window recalc |
| HEADER | 3 | Header row re-render |
| ROWS | 4 | Data row re-render |
| COLUMNS | 5 | Column structure rebuild |
| FULL | 6 | Complete re-render |

When multiple phases are requested in the same frame, only the highest-priority phase executes (it inherently covers lower phases).

## Bundle Size Optimization

### Tree-Shaking Features

The most important optimization: **only import the features you use**.

```typescript
// ✅ Optimal: ~45 KB core + only features you need
import '@toolbox-web/grid';
import '@toolbox-web/grid/features/selection';
import '@toolbox-web/grid/features/editing';

// ❌ Heavy: imports ALL plugins even if you use two
import '@toolbox-web/grid/all';
```

### Budget Reference

| Bundle | Raw | Gzipped |
|--------|-----|---------|
| Core (`index.js`) | ≤ 170 KB | ≤ 50 KB (soft warning at 45 KB) |
| Individual plugin | 2–15 KB | 1–5 KB |
| All plugins (`all.js`) | ~300 KB | ~80 KB |

## Tuning for Large Datasets

### Fixed Row Heights

Variable row heights (`rowHeight: (row) => number`) require measuring each row, which is slower than fixed heights. For datasets over 10,000 rows, prefer fixed heights:

```typescript
grid.gridConfig = {
  rowHeight: 32,
};
```

### Disable Animations

Row animations add visual polish but cost CPU cycles. Disable them for very large datasets:

```typescript
grid.gridConfig = {
  animation: { mode: 'off' },
};
```

By default `mode` is `'reduced-motion'` — animations are already disabled when the user has `prefers-reduced-motion: reduce` set.

### Batch Data Updates

When updating many rows, assign the entire array at once rather than using `insertRow()` / `removeRow()` in a loop:

```typescript
// ✅ Single assignment — triggers one sort/filter/render cycle
grid.rows = updatedData;

// ❌ Loop — triggers N animations and N re-renders
for (const newRow of newRows) {
  await grid.insertRow(0, newRow);
}
```

### Debounce Filtering

When using filtering with a large dataset, increase the debounce to reduce re-filtering:

```typescript
import '@toolbox-web/grid/features/filtering';

grid.gridConfig = {
  features: { filtering: { debounceMs: 300 } }, // Default: 200
};
```

### Custom Sort Comparators

For fields with expensive comparisons, provide a custom `sortComparator`:

```typescript
{
  field: 'name',
  sortable: true,
  sortComparator: (a: string, b: string) =>
    a.localeCompare(b, undefined, { sensitivity: 'base' }),
}
```

## Rendering Best Practices

### Avoid Direct DOM Manipulation

Let the grid manage its DOM. Direct manipulation can conflict with the render scheduler and virtualization:

```typescript
// ❌ Don't do this — bypasses the grid's render cycle
document.querySelector('.data-grid-row')!.style.background = 'red';

// ✅ Use rowClass/cellClass or a renderer instead
grid.gridConfig = {
  rowClass: (row) => row.status === 'error' ? 'row-error' : '',
};
```

### Use `registerStyles()` for Dynamic Runtime CSS

Standard CSS (stylesheets, `<style>` in `<head>`) works fine for static styles. For styles you need to inject or toggle **from JavaScript at runtime**, use `registerStyles()` instead of appending `<style>` elements inside the grid (which get removed by `replaceChildren()`):

```typescript
grid.registerStyles('my-highlights', `
  .highlight-row { background: yellow; }
`);

// Clean up when done
grid.unregisterStyles('my-highlights');
```

### Prefer Formatters Over Renderers

Formatters return a plain string — significantly faster than creating DOM elements via a renderer. Use a renderer only when you need interactive elements or custom HTML structure:

```typescript
// ✅ Fast — formatter returns a string (no DOM creation)
{ field: 'salary', format: (v) => `$${v.toFixed(2)}` }

// ⚠️ Slower — renderer creates DOM elements (use only when needed)
{ field: 'status', renderer: (ctx) => {
  const badge = document.createElement('span');
  badge.className = `badge-${ctx.value}`;
  badge.textContent = String(ctx.value);
  return badge;
}}
```

## Profiling

### Scale-tier reference

Use this table to set expectations and pick which knobs matter for your dataset. All numbers assume the default plugin set on a 2023-class laptop (M-series Mac / Ryzen 7).

| Rows × Cols | What to expect | What you'll tune |
|---|---|---|
| **≤ 1k × 20** | Instant — no tuning needed | Nothing |
| **10k × 20** | Smooth 60fps scroll / sort < 50ms | `rowHeight: number` (fixed) over variable; prefer `format` over `renderer` |
| **100k × 20** | Smooth scroll; sort 200-500ms (single-threaded JS) | Same as above + `getRowId` for stable identity; consider [Server-Side](/grid/plugins/server-side.md) for queries |
| **1M+ rows** | Don't load into memory — paginate or use [Server-Side](/grid/plugins/server-side.md) | Server-Side plugin with infinite scroll |
| **× 50+ columns** | Horizontal scroll may stutter without column virtualization | Enable [`ColumnVirtualizationPlugin`](/grid/plugins/column-virtualization.md) |

### Profile your own app

The "is the grid slow?" question is almost always one of: (a) **the grid is doing too much work** (too many columns rendered, expensive renderers, layout thrashing from outside the grid); or (b) **your data pipeline is slow** (re-allocating row arrays, re-deriving columns on every render, heavy formatters). The DevTools Performance tab can tell the two apart in 60 seconds.

1. **Record a representative interaction.** Open Chrome DevTools → Performance → click ⏺ Record → do the slow thing (scroll, sort, filter, edit) for 2-3 seconds → stop.
2. **Find the long tasks.** Anything > 50ms shows up as a red triangle. Click into the flame graph.
3. **Read the stack:**
   - **`renderScheduler.flush` dominates** → grid-internal work. Look one level deeper:
     - `renderRow` / `updateRowDom` heavy → your `renderer` or `cellClass` is slow. Switch to `format` if you only return text.
     - `measureRow` heavy → variable row heights with expensive content. Set a fixed `rowHeight` or memoize.
     - `applyColumns` heavy → too many visible columns. Enable [`ColumnVirtualizationPlugin`](/grid/plugins/column-virtualization.md).
   - **Framework code (React reconciler / Angular CD / Vue render) dominates** → your wrapper is re-rendering the grid on unrelated state changes. Pass `rows` / `gridConfig` as a stable reference (`useMemo`, `computed`, `signal`).
   - **`Recalculate Style` / `Layout` dominate, outside the grid** → something on the page is reacting to the grid's resize. Usually a parent flexbox or a `ResizeObserver` you wrote.

4. **Mark your own boundaries** to make the trace readable:

   ```ts
   performance.mark('app:load-rows:start');
   grid.rows = bigArray;
   await new Promise(r => requestAnimationFrame(r));
   performance.mark('app:load-rows:end');
   performance.measure('app:load-rows', 'app:load-rows:start', 'app:load-rows:end');
   ```

   `performance.measure()` entries show up as labeled bars at the top of the flame chart.

5. **Compare against the [comparison page](/grid/comparison.md)** — if your numbers are very different from ours on a similar dataset, the cause is in your app code, not the grid.

### Key metrics to watch

| Metric | Target | How to measure |
|--------|--------|---------------|
| **Scroll FPS** | 60fps | DevTools → Performance → Frames row |
| **Sort time (10K rows)** | < 50ms | `console.time()` around `grid.rows = sorted` |
| **Filter time (10K rows)** | < 30ms | Measure in `filter-change` event handler |
| **Initial render** | < 100ms | Performance tab → First Paint |
| **Memory (100K rows)** | < 100 MB | Memory tab → Heap snapshot |

## Stress Test

Try the interactive stress test below — adjust row and column counts to see how the grid performs with large datasets:

```ts
// PerformanceStressTestDemo.astro
  import '@toolbox-web/grid';
import type { ColumnConfig } from '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/column-virtualization';
import '@toolbox-web/grid/features/filtering';
import '@toolbox-web/grid/features/multi-sort';
import '@toolbox-web/grid/features/pinned-columns';
import '@toolbox-web/grid/features/selection';

  // #region Types & Helpers
  type ExtendedColumnConfig = ColumnConfig & { sticky?: 'left' | 'right'; filterable?: boolean };

  interface BenchmarkResult {
    name: string;
    category: 'render' | 'scroll' | 'operation' | 'memory';
    time: number;
    unit: string;
    target: number;
    passed: boolean;
    note?: string;
  }

  function generateColumns(count: number, options?: { sortable?: boolean; filterable?: boolean }): ExtendedColumnConfig[] {
    const columns: ExtendedColumnConfig[] = [
      { field: 'id', header: 'ID', type: 'number', width: 60, sortable: options?.sortable },
    ];
    for (let i = 1; i < count; i++) {
      columns.push({
        field: `col${i}`,
        header: `Column ${i}`,
        type: 'string',
        width: 100,
        sortable: options?.sortable,
        filterable: options?.filterable,
      });
    }
    return columns;
  }

  function generateRows(rowCount: number, columnCount: number): Record<string, unknown>[] {
    const rows: Record<string, unknown>[] = [];
    for (let i = 0; i < rowCount; i++) {
      const row: Record<string, unknown> = { id: i + 1 };
      for (let j = 1; j < columnCount; j++) {
        row[`col${j}`] = `R${i + 1}C${j}`;
      }
      rows.push(row);
    }
    return rows;
  }

  function formatTime(ms: number): string {
    if (ms < 1) return `${(ms * 1000).toFixed(0)}µs`;
    if (ms < 1000) return `${ms.toFixed(2)}ms`;
    return `${(ms / 1000).toFixed(2)}s`;
  }

  function formatBytes(bytes: number): string {
    if (bytes < 1024) return bytes + ' B';
    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
    return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
  }
  // #endregion

  // #region Results Rendering
  function renderResultsTable(results: BenchmarkResult[], isComplete = false): string {
    const categories = ['render', 'scroll', 'operation', 'memory'] as const;
    const categoryLabels: Record<string, string> = {
      render: '🎨 Initial Render',
      scroll: '📜 Scroll Performance',
      operation: '⚡ Operations',
      memory: '💾 Memory',
    };

    let html = `<div style="display:grid;grid-template-columns:repeat(2,1fr);gap:16px;">`;

    for (const cat of categories) {
      const catResults = results.filter((r) => r.category === cat);
      if (catResults.length === 0) continue;

      html += `
        <div style="background:var(--sl-color-gray-6,#1e1e1e);border-radius:6px;padding:12px;min-width:0;">
          <h4 style="margin:0 0 10px 0;color:var(--sl-color-white,#e5e5e5);font-size:13px;font-weight:600;">${categoryLabels[cat]}</h4>
          <div style="display:grid;grid-template-columns:1fr auto auto auto;gap:4px 12px;font-size:12px;align-items:center;">
            ${catResults.map((r) => `
              <div style="color:var(--sl-color-white,#e5e5e5);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;">${r.name}</div>
              <div style="color:${r.passed ? '#4ade80' : '#f87171'};font-family:monospace;text-align:right;">
                ${r.unit === 'info' ? '—' : r.unit === 'bytes' ? formatBytes(r.time) : r.unit === 'bool' ? (r.time ? 'Yes' : 'No') : r.unit === 'count' ? r.time.toLocaleString() : formatTime(r.time)}
              </div>
              <div style="color:#888;font-family:monospace;text-align:right;font-size:11px;max-width:180px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;" title="${r.note || ''}">
                ${r.note ? r.note : (r.unit === 'bool' || r.unit === 'info' || r.unit === 'count') ? '' : r.target === Infinity ? '(info)' : '&lt;' + (r.unit === 'bytes' ? formatBytes(r.target) : formatTime(r.target))}
              </div>
              <div style="text-align:center;">${r.target === Infinity ? 'ℹ️' : r.passed ? '✅' : '❌'}</div>
            `).join('')}
          </div>
        </div>
      `;
    }

    html += `</div>`;

    if (isComplete) {
      const passed = results.filter((r) => r.passed).length;
      const total = results.length;
      const allPassed = passed === total;
      html += `
        <div style="margin-top:16px;padding:12px;background:${allPassed ? '#166534' : '#991b1b'};border-radius:4px;text-align:center;">
          <strong style="color:#fff;font-size:14px;">${allPassed ? '✅ All benchmarks passed!' : `⚠️ ${passed}/${total} benchmarks passed`}</strong>
        </div>
      `;
    } else {
      html += `<div style="margin-top:16px;padding:8px;opacity:0.6;text-align:center;font-size:12px;">Running... ${results.length} tests completed</div>`;
    }

    return html;
  }
  // #endregion

  // #region DOM References
  const grid = queryGrid('#demo-perf-stress')!;
  const rowsSlider = document.getElementById('stress-rows') as HTMLInputElement;
  const colsSlider = document.getElementById('stress-cols') as HTMLInputElement;
  const rowsVal = document.getElementById('stress-rows-val')!;
  const colsVal = document.getElementById('stress-cols-val')!;
  const runBtn = document.getElementById('stress-run') as HTMLButtonElement;
  const statusEl = document.getElementById('stress-status')!;
  const resultsEl = document.getElementById('stress-results')!;
  // #endregion

  // #region Slider Handlers
  function getRowCount() { return parseInt(rowsSlider.value, 10); }
  function getColCount() { return parseInt(colsSlider.value, 10); }

  rowsSlider.addEventListener('input', () => {
    rowsVal.textContent = getRowCount().toLocaleString();
    updateStatus();
  });
  colsSlider.addEventListener('input', () => {
    colsVal.textContent = String(getColCount());
    updateStatus();
  });

  function updateStatus() {
    statusEl.textContent = `Ready - ${getRowCount().toLocaleString()} rows × ${getColCount()} columns`;
  }

  function applyInitialData() {
    const rowCount = getRowCount();
    const colCount = getColCount();
    statusEl.textContent = `Ready - ${rowCount.toLocaleString()} rows × ${colCount} columns`;
    grid.gridConfig = {
      columns: generateColumns(colCount, { sortable: true, filterable: true }),
      fitMode: 'fixed',
      features: {
        selection: 'range',
        pinnedColumns: true,
        multiSort: { maxSortColumns: 3 },
        filtering: { debounceMs: 0 },
        ...(colCount >= 20 ? { columnVirtualization: { threshold: 20, overscan: 3 } } : {}),
      },
    };
    grid.rows = generateRows(rowCount, colCount);
  }

  // Show initial status without generating data
  updateStatus();
  // #endregion

  // #region Benchmark Runner
  runBtn.addEventListener('click', async () => {
    runBtn.disabled = true;
    const allResults: BenchmarkResult[] = [];
    const rowCount = getRowCount();
    const colCount = getColCount();

    const updateResults = () => { resultsEl.innerHTML = renderResultsTable(allResults); };

    const nextFrame = () => new Promise<void>((r) => requestAnimationFrame(() => r()));

    const measure = async (fn: () => void | Promise<void>): Promise<number> => {
      await nextFrame();
      const start = performance.now();
      await fn();
      await nextFrame();
      return performance.now() - start;
    };

    // Scaling
    const baselineRows = 10_000;
    const baselineCols = 10;
    const rowScale = Math.max(1, Math.sqrt(rowCount / baselineRows));
    const colScale = Math.max(1, Math.sqrt(colCount / baselineCols));
    const cellScale = rowScale * colScale;
    const scaledByRows = (base: number) => Math.round(base * rowScale);
    const scaledByCells = (base: number) => Math.round(base * cellScale);

    const baseColumns = generateColumns(colCount, { sortable: true, filterable: true });
    const baseRows = generateRows(rowCount, colCount);

    // 🎨 INITIAL RENDER
    statusEl.textContent = 'Testing: Initial render (baseline)...';
    grid.gridConfig = { columns: [] };
    grid.rows = [];
    await new Promise((r) => setTimeout(r, 50));

    const renderTime = await measure(() => {
      grid.columns = baseColumns;
      grid.rows = [...baseRows];
    });
    allResults.push({ name: 'Baseline render', category: 'render', time: renderTime, unit: 'ms', target: scaledByCells(100), passed: renderTime < scaledByCells(100) });
    updateResults();

    // Render with features
    statusEl.textContent = 'Testing: Initial render (with features)...';
    grid.gridConfig = { columns: [] };
    grid.rows = [];
    await new Promise((r) => setTimeout(r, 50));

    const pluginColumns = baseColumns.map((col, i) => ({ ...col, sticky: i === 0 ? ('left' as const) : undefined }));
    const pluginRenderTime = await measure(() => {
      grid.gridConfig = {
        columns: pluginColumns as ColumnConfig[],
        fitMode: 'fixed',
        features: {
          selection: 'range',
          pinnedColumns: true,
          multiSort: { maxSortColumns: 3 },
          filtering: { debounceMs: 0 },
          columnVirtualization: { threshold: 20, overscan: 3 },
        },
      };
      grid.rows = [...baseRows];
    });
    allResults.push({ name: 'Render with 5 features', category: 'render', time: pluginRenderTime, unit: 'ms', target: scaledByCells(150), passed: pluginRenderTime < scaledByCells(150) });
    updateResults();

    // Warm render
    statusEl.textContent = 'Testing: Warm render (second render)...';
    const warmRows = generateRows(rowCount, colCount);
    const warmRenderTime = await measure(() => { grid.rows = warmRows; });
    allResults.push({ name: 'Warm render (data swap)', category: 'render', time: warmRenderTime, unit: 'ms', target: scaledByRows(50), passed: warmRenderTime < scaledByRows(50), note: warmRenderTime < pluginRenderTime ? 'Faster than cold ✓' : 'Slower than cold ⚠' });
    updateResults();

    // Time to interactive
    statusEl.textContent = 'Testing: Time to interactive...';
    grid.gridConfig = { columns: [] };
    grid.rows = [];
    await new Promise((r) => setTimeout(r, 50));
    const ttiStart = performance.now();
    grid.gridConfig = {
      columns: pluginColumns as ColumnConfig[],
      fitMode: 'fixed',
      features: {
        selection: 'range',
        pinnedColumns: true,
        multiSort: { maxSortColumns: 3 },
        filtering: { debounceMs: 0 },
        columnVirtualization: { threshold: 20, overscan: 3 },
      },
    };
    grid.rows = [...baseRows];
    await nextFrame();
    const headerCell = grid.querySelector('[role="columnheader"]') as HTMLElement | null;
    if (headerCell) { headerCell.click(); await nextFrame(); }
    const ttiTime = performance.now() - ttiStart;
    allResults.push({ name: 'Time to interactive', category: 'render', time: ttiTime, unit: 'ms', target: scaledByCells(200), passed: ttiTime < scaledByCells(200) });
    updateResults();

    // 📜 SCROLL PERFORMANCE
    statusEl.textContent = 'Testing: Scroll performance...';
    await new Promise((r) => setTimeout(r, 100));
    const scrollContainer = grid.querySelector('.faux-vscroll');
    if (scrollContainer) {
      const totalHeight = scrollContainer.scrollHeight;
      const viewportHeight = scrollContainer.clientHeight;
      const steps = 30;
      const stepSize = (totalHeight - viewportHeight) / steps;

      if (stepSize > 0) {
        // Warm-up
        for (let i = 0; i <= steps; i++) { scrollContainer.scrollTop = i * stepSize; await nextFrame(); }
        scrollContainer.scrollTop = 0;
        await new Promise((r) => setTimeout(r, 50));

        // Measure
        const frameTimes: number[] = [];
        for (let i = 0; i <= steps; i++) {
          const start = performance.now();
          scrollContainer.scrollTop = i * stepSize;
          await nextFrame();
          frameTimes.push(performance.now() - start);
        }

        const avgScroll = frameTimes.reduce((a, b) => a + b, 0) / frameTimes.length;
        const p95Scroll = [...frameTimes].sort((a, b) => a - b)[Math.floor(frameTimes.length * 0.95)];
        const p99Scroll = [...frameTimes].sort((a, b) => a - b)[Math.floor(frameTimes.length * 0.99)];
        const scrollTarget = Math.min(33.33, 17 * (1 + (colCount - 10) / 40));

        allResults.push({ name: 'Scroll avg frame', category: 'scroll', time: avgScroll, unit: 'ms', target: scrollTarget, passed: avgScroll < scrollTarget });
        allResults.push({ name: 'Scroll P95 frame', category: 'scroll', time: p95Scroll, unit: 'ms', target: 33.33, passed: p95Scroll < 33.33 });
        allResults.push({ name: 'Scroll P99 frame', category: 'scroll', time: p99Scroll, unit: 'ms', target: 50, passed: p99Scroll < 50 });
        updateResults();

        // Stress scroll
        statusEl.textContent = 'Testing: Stress scroll (random jumps)...';
        scrollContainer.scrollTop = 0;
        await new Promise((r) => setTimeout(r, 50));
        const stressJumps = 20;
        const stressFrameTimes: number[] = [];
        for (let i = 0; i < stressJumps; i++) {
          const randomPos = Math.random() * (totalHeight - viewportHeight);
          const start = performance.now();
          scrollContainer.scrollTop = randomPos;
          await nextFrame();
          stressFrameTimes.push(performance.now() - start);
        }
        const avgStressScroll = stressFrameTimes.reduce((a, b) => a + b, 0) / stressFrameTimes.length;
        const maxStressScroll = Math.max(...stressFrameTimes);
        allResults.push({ name: 'Stress scroll avg', category: 'scroll', time: avgStressScroll, unit: 'ms', target: 50, passed: avgStressScroll < 50 });
        allResults.push({ name: 'Stress scroll max', category: 'scroll', time: maxStressScroll, unit: 'ms', target: 100, passed: maxStressScroll < 100 });
        updateResults();
        scrollContainer.scrollTop = 0;
        await new Promise((r) => setTimeout(r, 50));
      }
    }

    // Horizontal scroll
    statusEl.textContent = 'Testing: Horizontal scroll performance...';
    await new Promise((r) => setTimeout(r, 100));
    const hScrollContainer = grid.querySelector('.tbw-scroll-area');
    const colVirtPlugin = (grid as any).getPluginByName?.('columnVirtualization');
    if (hScrollContainer && colCount >= 20) {
      const totalWidth = hScrollContainer.scrollWidth;
      const viewportWidth = hScrollContainer.clientWidth;
      const hSteps = 30;
      const hStepSize = (totalWidth - viewportWidth) / hSteps;
      if (hStepSize > 0) {
        for (let i = 0; i <= hSteps; i++) { hScrollContainer.scrollLeft = i * hStepSize; await nextFrame(); }
        hScrollContainer.scrollLeft = 0;
        await new Promise((r) => setTimeout(r, 50));
        const hFrameTimes: number[] = [];
        for (let i = 0; i <= hSteps; i++) {
          const start = performance.now();
          hScrollContainer.scrollLeft = i * hStepSize;
          await nextFrame();
          hFrameTimes.push(performance.now() - start);
        }
        const avgHScroll = hFrameTimes.reduce((a, b) => a + b, 0) / hFrameTimes.length;
        const p95HScroll = [...hFrameTimes].sort((a, b) => a - b)[Math.floor(hFrameTimes.length * 0.95)];
        allResults.push({ name: 'H-Scroll avg frame', category: 'scroll', time: avgHScroll, unit: 'ms', target: 50, passed: avgHScroll < 50 });
        allResults.push({ name: 'H-Scroll P95 frame', category: 'scroll', time: p95HScroll, unit: 'ms', target: 66.67, passed: p95HScroll < 66.67 });
        if (colVirtPlugin) {
          const isVirt = colVirtPlugin.getIsVirtualized();
          const range = colVirtPlugin.getVisibleColumnRange();
          allResults.push({ name: `Col virtualization (${range.end - range.start + 1}/${colCount} visible)`, category: 'scroll', time: isVirt ? 1 : 0, unit: 'bool', target: 1, passed: isVirt });
        }
        updateResults();
      }
    }

    // ⚡ OPERATIONS
    // Sort
    statusEl.textContent = 'Testing: Sort operation...';
    if (scrollContainer) scrollContainer.scrollTop = 0;
    await new Promise((r) => setTimeout(r, 50));
    const sortPlugin = (grid as any).getPluginByName?.('multiSort') as { setSortModel: (m: unknown[]) => void; clearSort: () => void } | undefined;
    if (sortPlugin) {
      const sortTarget = Math.round(150 * (Math.log2(rowCount) / Math.log2(10000)));
      const sortTime = await measure(() => { sortPlugin.setSortModel([{ field: 'id', direction: 'asc' }]); });
      allResults.push({ name: 'Sort (ascending)', category: 'operation', time: sortTime, unit: 'ms', target: sortTarget, passed: sortTime < sortTarget });
      updateResults();

      grid.rows = generateRows(rowCount, colCount);
      await nextFrame();
      await new Promise((r) => setTimeout(r, 50));
      const reverseSortTime = await measure(() => { sortPlugin.setSortModel([{ field: 'id', direction: 'desc' }]); });
      allResults.push({ name: 'Sort (descending)', category: 'operation', time: reverseSortTime, unit: 'ms', target: sortTarget, passed: reverseSortTime < sortTarget });
      updateResults();
      sortPlugin.clearSort();
      await nextFrame();
    }

    // Filter
    statusEl.textContent = 'Testing: Filter operation...';
    const filterPlugin = (grid as any).getPluginByName?.('filtering') as { setFilter: (f: string, v: unknown) => void } | undefined;
    if (filterPlugin) {
      const filterTime = await measure(() => { filterPlugin.setFilter('col1', { type: 'text', operator: 'contains', value: 'R1' }); });
      allResults.push({ name: 'Filter (to ~10%)', category: 'operation', time: filterTime, unit: 'ms', target: scaledByRows(50), passed: filterTime < scaledByRows(50) });
      updateResults();
      const clearFilterTime = await measure(() => { filterPlugin.setFilter('col1', null); });
      allResults.push({ name: 'Clear filter', category: 'operation', time: clearFilterTime, unit: 'ms', target: scaledByRows(50), passed: clearFilterTime < scaledByRows(50) });
      updateResults();
    }

    // Data replacement
    statusEl.textContent = 'Testing: Data replacement...';
    const newRows = generateRows(rowCount, colCount);
    const replaceTime = await measure(() => { grid.rows = newRows; });
    allResults.push({ name: 'Full data replace', category: 'operation', time: replaceTime, unit: 'ms', target: scaledByRows(50), passed: replaceTime < scaledByRows(50) });
    updateResults();

    // Selection
    statusEl.textContent = 'Testing: Selection...';
    const selectionPlugin = (grid as any).getPluginByName?.('selection') as { setRanges: (r: unknown[]) => void; clearSelection: () => void } | undefined;
    if (selectionPlugin) {
      const selectAllTime = await measure(() => {
        selectionPlugin.setRanges([{ from: { row: 0, col: 0 }, to: { row: rowCount - 1, col: colCount - 1 } }]);
      });
      allResults.push({ name: 'Select all cells', category: 'operation', time: selectAllTime, unit: 'ms', target: 50, passed: selectAllTime < 50 });
      updateResults();
      const clearSelectionTime = await measure(() => { selectionPlugin.clearSelection(); });
      allResults.push({ name: 'Clear selection', category: 'operation', time: clearSelectionTime, unit: 'ms', target: 50, passed: clearSelectionTime < 50 });
      updateResults();
    }

    // Rapid data updates
    statusEl.textContent = 'Testing: Rapid data updates...';
    const updateCount = 10;
    const updateTimes: number[] = [];
    for (let i = 0; i < updateCount; i++) {
      const modifiedRows = [...grid.rows] as Record<string, unknown>[];
      const updateSize = Math.max(1, Math.floor(rowCount * 0.01));
      for (let j = 0; j < updateSize; j++) {
        const idx = (i * updateSize + j) % rowCount;
        modifiedRows[idx] = { ...modifiedRows[idx], col1: `Updated-${i}-${j}` };
      }
      const t = await measure(() => { grid.rows = modifiedRows; });
      updateTimes.push(t);
    }
    const avgUpdateTime = updateTimes.reduce((a, b) => a + b, 0) / updateTimes.length;
    allResults.push({ name: `Rapid update (${updateCount}× 1%)`, category: 'operation', time: avgUpdateTime, unit: 'ms', target: scaledByRows(30), passed: avgUpdateTime < scaledByRows(30) });
    updateResults();

    // Column config change
    statusEl.textContent = 'Testing: Column config change...';
    const configChangeTime = await measure(() => {
      const newColumns = baseColumns.map((col, i) => ({ ...col, width: i === 1 ? 200 : col.width }));
      grid.columns = newColumns;
    });
    allResults.push({ name: 'Column config change', category: 'operation', time: configChangeTime, unit: 'ms', target: scaledByCells(50), passed: configChangeTime < scaledByCells(50) });
    updateResults();

    // Column resize
    statusEl.textContent = 'Testing: Column resize performance...';
    const resizeFrameTimes: number[] = [];
    for (let i = 0; i < 20; i++) {
      const width = 80 + (i % 2 === 0 ? 40 : -20);
      const start = performance.now();
      grid.columns = baseColumns.map((col, idx) => ({ ...col, width: idx === 1 ? width : col.width }));
      await nextFrame();
      resizeFrameTimes.push(performance.now() - start);
    }
    const avgResize = resizeFrameTimes.reduce((a, b) => a + b, 0) / resizeFrameTimes.length;
    const p95Resize = [...resizeFrameTimes].sort((a, b) => a - b)[Math.floor(resizeFrameTimes.length * 0.95)];
    allResults.push({ name: 'Resize avg frame', category: 'operation', time: avgResize, unit: 'ms', target: 33.33, passed: avgResize < 33.33 });
    allResults.push({ name: 'Resize P95 frame', category: 'operation', time: p95Resize, unit: 'ms', target: 50, passed: p95Resize < 50 });
    updateResults();

    // 💾 MEMORY
    statusEl.textContent = 'Calculating: Memory & DOM metrics...';
    const estimatedBytesPerRow = 40 + colCount * 52;
    const estimatedDataSize = rowCount * estimatedBytesPerRow;
    allResults.push({ name: 'Est. data size', category: 'memory', time: estimatedDataSize, unit: 'bytes', target: 500 * 1024 * 1024, passed: estimatedDataSize < 500 * 1024 * 1024 });
    allResults.push({ name: 'Est. bytes/row', category: 'memory', time: estimatedBytesPerRow, unit: 'bytes', target: 5000, passed: estimatedBytesPerRow < 5000 });

    const rowElements = grid.querySelectorAll('.data-grid-row');
    const renderedRowCount = rowElements?.length ?? 0;
    const maxExpectedRows = Math.min(rowCount, 100);
    allResults.push({ name: `DOM rows (${renderedRowCount}/${rowCount.toLocaleString()})`, category: 'memory', time: renderedRowCount, unit: 'count', target: maxExpectedRows, passed: renderedRowCount <= maxExpectedRows, note: renderedRowCount <= maxExpectedRows ? 'Virtualization active' : 'Too many DOM nodes!' });

    const cellElements = grid.querySelectorAll('.cell');
    const renderedCellCount = cellElements?.length ?? 0;
    const expectedCellsPerRow = colCount <= 20 ? colCount : Math.min(colCount, 30);
    const maxExpectedCells = maxExpectedRows * expectedCellsPerRow;
    allResults.push({ name: 'DOM cells rendered', category: 'memory', time: renderedCellCount, unit: 'count', target: maxExpectedCells, passed: renderedCellCount <= maxExpectedCells, note: `${renderedCellCount.toLocaleString()} cells in DOM` });
    updateResults();

    // COMPLETE
    statusEl.textContent = 'Benchmark complete!';
    runBtn.disabled = false;
    resultsEl.innerHTML = renderResultsTable(allResults, true);

    console.table(allResults.map((r) => ({
      Benchmark: r.name,
      Result: r.unit === 'bytes' ? formatBytes(r.time) : r.unit === 'count' ? r.time.toLocaleString() : r.unit === 'bool' ? (r.time ? 'Yes' : 'No') : r.unit === 'info' ? (r.note || '—') : formatTime(r.time),
      Target: r.unit === 'bytes' ? '< ' + formatBytes(r.target) : r.unit === 'count' || r.unit === 'bool' || r.unit === 'info' ? (r.note || '—') : '< ' + formatTime(r.target),
      Status: r.passed ? '✅ PASS' : '❌ FAIL',
    })));
  });
  // #endregion
```

## See Also

  - [Compared to other grids](/grid/comparison.md): Live benchmarks vs AG Grid, Tabulator, SlickGrid — runnable in your browser
  - [Architecture](/grid/architecture.md): How the render scheduler and virtualization work internally
  - [Column Virtualization](/grid/plugins/column-virtualization.md): Render only visible columns for wide grids (50+ columns)
  - [Server-Side Plugin](/grid/plugins/server-side.md): Stream rows for million-row datasets without loading them into memory

---

# Production Checklist

> A scannable pre-launch checklist for shipping @toolbox-web/grid to production. Each item links to the deep guide.

Use this list **right before you ship**. Each item is one line; click through to the deep guide for the *how* and *why*. If you can tick every box, you're production-ready.

## Security

- [ ] **Sanitize external data** before assigning to `grid.rows` — validate types, ensure unique row IDs, strip unexpected fields.
- [ ] **No `innerHTML` from user input** in custom renderers. Use `textContent`, or sanitize with DOMPurify first. See [Renderer security](/grid/core.md#renderer-security-avoid-innerhtml).
- [ ] **CSP allows `style-src 'self'`** — the grid injects styles via `adoptedStyleSheets`. See [Styles not applying (CSP)](/grid/guides/troubleshooting.md#styles-not-applying-csp).

## Performance

- [ ] **Only the features you use are imported** (or use `/features/*` side-effect imports for tree-shaking). Avoid `@toolbox-web/grid/all` in production.
- [ ] **Fixed `rowHeight`** set for datasets over a few thousand rows. See [Performance guide](/grid/guides/performance.md#scale-tier-reference).
- [ ] **Column virtualization** enabled if you render 50+ columns. See [`ColumnVirtualizationPlugin`](/grid/plugins/column-virtualization.md).
- [ ] **Server-side loading** considered for million-row datasets. See [`ServerSidePlugin`](/grid/plugins/server-side.md).
- [ ] **Bundle size measured** — your final grid bundle is within the [bundle budget](/grid/guides/performance.md#why-its-fast).

## Reliability

- [ ] **Async data fetches handle failure** — `grid.loading` toggled, errors caught, user shown a message.
- [ ] **Grid configuration wrapped in try/catch** as a safety net — [TBW configuration errors](/grid/errors.md) include import hints, but should not crash your app.
- [ ] **Stable `getRowId`** if your rows can be re-fetched / re-sorted — keeps selection, focus, and edit state correct.
- [ ] **Automated tests cover the critical paths** (sort, filter, edit, selection) and use the [stable selector contract](/grid/guides/automated-testing.md) — not visual indices or framework-generated class names.

## Accessibility

- [ ] **Grid has an accessible name** — via `<tbw-grid-header title="…">`, `gridAriaLabel`, `gridAriaLabelledBy`, or `aria-label`.
- [ ] **Tab → arrow keys → Enter → Escape** all work as described in the [Accessibility guide](/grid/guides/accessibility.md).
- [ ] **Tested with at least one screen reader** (NVDA, VoiceOver, or JAWS) — see [Testing with screen readers](/grid/guides/accessibility.md#testing-with-screen-readers).
- [ ] **Forced-colors / Windows High Contrast** verified visually.

## Monitoring (optional but recommended)

- [ ] **Track sort / filter / selection events** (`sort-change`, `filter-change`, `selection-change`) to understand how users use the grid in production.
- [ ] **Sentry / equivalent** captures any uncaught grid errors with the [TBW error code](/grid/errors.md) intact (it's in the message).

## See also

  - [Performance](/grid/guides/performance.md): Profiling, virtualization tuning, and scale-tier reference
  - [Accessibility](/grid/guides/accessibility.md): WCAG 2.1 AA, screen reader testing, focus management
  - [Troubleshooting](/grid/guides/troubleshooting.md): Common deployment issues and fixes
  - [Automated testing](/grid/guides/automated-testing.md): Playwright, Cypress, and WebdriverIO recipes
  - [Error Codes](/grid/errors.md): TBW error code reference

---

# Theming

> Customize @toolbox-web/grid with CSS custom properties — colors, spacing, typography, dark mode, pre-built themes, and cascade layers.

The `@toolbox-web/grid` component is fully themeable via CSS custom properties. Customize colors, spacing, typography, and more without modifying source code.

## Quick Start

Override CSS custom properties on the grid element. Use the combined
`[data-tbw-grid], tbw-grid` selector — it matches the canonical `<tbw-grid>`
tag *and* version-suffixed tags (e.g. `<tbw-grid-v2-14-0>`) emitted when
[multiple grid versions](./multi-version) share the page:

```css
[data-tbw-grid],
tbw-grid {
  --tbw-color-bg: #1a1a2e;
  --tbw-color-fg: #eaeaea;
  --tbw-color-border: #16213e;
  --tbw-color-header-bg: #0f3460;
  --tbw-color-row-hover: #1a1a4e;
}
```

:::caution[Themes targeting only `tbw-grid` break in micro-frontends]
If your theme might ever be loaded into a micro-frontend host where another
bundle already owns `tbw-grid`, your bundle will register itself under a
suffixed tag (e.g. `tbw-grid-v2-14-0`) and any rule keyed on the bare
`tbw-grid` selector will silently miss those grids. **Always include
`[data-tbw-grid]` in custom theme selectors** — every grid sets that
attribute on its host regardless of the registered tag. The bundled
themes (`@toolbox-web/grid/themes/dg-theme-*.css`) already follow this
convention. See [Multi-version coexistence](./multi-version) for details.
:::

## Scaling with Font Size

All sizing uses `em` units, so the grid scales proportionally with `font-size`:

```css
tbw-grid { font-size: 1.25em; }           /* 25% larger */
tbw-grid.compact { font-size: 0.875em; }  /* Compact */
```

## Pre-built Themes

Import a pre-built theme CSS file:

```typescript
import '@toolbox-web/grid/themes/dg-theme-material.css';
```

| Theme | Description |
| --- | --- |
| **Standard** | Polished, balanced look |
| **Material** | Material Design 3 inspired |
| **Bootstrap** | Bootstrap 5 styling |
| **Vibrant** | Bold purple accents |
| **Contrast** | High contrast for accessibility |
| **Large** | Larger fonts and spacing |

## Dark Mode Support

The grid uses `light-dark()` for automatic theme support:

```css
tbw-grid { color-scheme: light dark; }  /* Auto-adapt */
tbw-grid { color-scheme: dark; }        /* Force dark */
```

All built-in color variables use `light-dark()` internally, so they automatically provide appropriate colors for both modes.

## CSS Cascade Layers

The grid organizes its styles into CSS cascade layers:

```css
@layer tbw-base, tbw-plugins, tbw-theme;
```

Your unlayered CSS always wins — no `!important` needed. This makes theming predictable:

- `tbw-base` — Core grid styles (structure, layout)
- `tbw-plugins` — Plugin-contributed styles (selection highlighting, filter icons, etc.)
- `tbw-theme` — Theme overrides (pre-built themes go here)
- *(unlayered)* — Your custom CSS — always highest priority

## Interactive Theme Builder

Use the theme builder below to customize every CSS variable in real-time — including core tokens and plugin-specific variables across all categories. The preview grid updates instantly as you tweak values. Export your theme as a `.css` file when you're done.

## CSS Variable Reference

The tables below list **all 228 CSS custom properties** across core styles and every plugin, with their **live computed values** in this page. Toggle between light and dark mode to see how values change.

### Core Colors

| Variable | Description |
| --- | --- |
| `--tbw-color-bg` | Grid background |
| `--tbw-color-panel-bg` | Panel backgrounds |
| `--tbw-color-fg` | Primary text color |
| `--tbw-color-fg-muted` | Secondary text |
| `--tbw-color-accent` | Accent color (focus, selection) |
| `--tbw-color-accent-fg` | Text on accent |
| `--tbw-color-success` | Success state |
| `--tbw-color-warning` | Warning state |
| `--tbw-color-error` | Error state |
| `--tbw-color-shadow` | Box‑shadow color |

### Row & Cell Colors

| Variable | Description |
| --- | --- |
| `--tbw-color-selection` | Selection background |
| `--tbw-color-row-alt` | Alternating row color |
| `--tbw-color-row-hover` | Row hover color |
| `--tbw-color-active-row-bg` | Active row background |

### Header

| Variable | Description |
| --- | --- |
| `--tbw-color-header-bg` | Header background |
| `--tbw-color-header-fg` | Header text color |
| `--tbw-color-header-separator` | Header column separator |
| `--tbw-color-header-group-fg` | Column group header text |
| `--tbw-header-height` | Header row height |
| `--tbw-font-size-header` | Header font size |
| `--tbw-font-weight-header` | Header font weight |
| `--tbw-font-weight-header-group` | Column group font weight |
| `--tbw-header-text-transform` | Header text transform |
| `--tbw-header-letter-spacing` | Header letter spacing |
| `--tbw-align-header` | Header content alignment |
| `--tbw-align-header-group` | Column group alignment |

### Borders

| Variable | Description |
| --- | --- |
| `--tbw-color-border` | Default border color |
| `--tbw-color-border-strong` | Strong border color |
| `--tbw-color-border-cell` | Cell border color |
| `--tbw-color-border-header` | Header border color |
| `--tbw-border-radius` | Border radius |
| `--tbw-border-width` | Default border width |
| `--tbw-border-style` | Default border style |
| `--tbw-border-input` | Input border shorthand |
| `--tbw-border-header` | Header border shorthand |
| `--tbw-row-divider` | Row divider border |
| `--tbw-row-hover-outline` | Row hover outline |
| `--tbw-active-row-outline` | Active row outline |

### Typography

| Variable | Description |
| --- | --- |
| `--tbw-font-family` | Font family |
| `--tbw-font-size` | Base font size |
| `--tbw-font-size-sm` | Small font size |
| `--tbw-font-size-xs` | Extra small font size |
| `--tbw-font-size-2xs` | Extra‑extra small font size |

### Spacing

| Variable | Description |
| --- | --- |
| `--tbw-spacing-xs` | Extra small spacing |
| `--tbw-spacing-sm` | Small spacing |
| `--tbw-spacing-md` | Medium spacing |
| `--tbw-spacing-lg` | Large spacing |
| `--tbw-spacing-xl` | Extra large spacing |
| `--tbw-cell-padding` | Cell padding |
| `--tbw-cell-padding-v` | Cell vertical padding |
| `--tbw-cell-padding-h` | Cell horizontal padding |
| `--tbw-cell-padding-header` | Header cell padding |
| `--tbw-cell-padding-input` | Input cell padding |

### Row & Cell Dimensions

| Variable | Description |
| --- | --- |
| `--tbw-row-height` | Row height |
| `--tbw-cell-white-space` | Cell text wrapping |
| `--tbw-density-scale` | Density multiplier |

### Focus & Selection

| Variable | Description |
| --- | --- |
| `--tbw-focus-outline-width` | Focus ring width |
| `--tbw-focus-outline` | Focus ring style |
| `--tbw-focus-outline-offset` | Focus ring offset |
| `--tbw-focus-background` | Focused cell background tint |
| `--tbw-range-border-color` | Range selection border |
| `--tbw-range-selection-bg` | Range selection background |

### Icons

| Variable | Description |
| --- | --- |
| `--tbw-base-icon-size` | Base icon size (bulk override) |
| `--tbw-icon-size` | Icon size |
| `--tbw-icon-size-sm` | Small icon size |
| `--tbw-checkbox-size` | Checkbox size |
| `--tbw-toggle-size` | Toggle icon size |

### Resize Handle

| Variable | Description |
| --- | --- |
| `--tbw-resize-handle-width` | Resize handle width |
| `--tbw-resize-handle-color` | Resize handle color |
| `--tbw-resize-handle-color-hover` | Resize handle hover color |
| `--tbw-resize-handle-border-radius` | Resize handle corner radius |
| `--tbw-resize-indicator-width` | Resize indicator width |
| `--tbw-resize-indicator-color` | Resize indicator color |
| `--tbw-resize-indicator-opacity` | Resize indicator opacity |
| `--tbw-resize-hit-area` | Resize handle clickable area |

### Animation

| Variable | Description |
| --- | --- |
| `--tbw-transition-duration` | Transition duration |
| `--tbw-transition-ease` | Transition easing |
| `--tbw-animation-duration` | Animation duration |
| `--tbw-animation-easing` | Animation easing |
| `--tbw-animation-enabled` | Enable animations (0 to disable) |
| `--tbw-row-change-duration` | Row change highlight duration |
| `--tbw-row-insert-duration` | Row insert animation duration |
| `--tbw-row-remove-duration` | Row remove animation duration |
| `--tbw-row-change-color` | Row change highlight color |

### Sorting Indicators

| Variable | Description |
| --- | --- |
| `--tbw-sort-indicator-color` | Sort indicator color |
| `--tbw-sort-indicator-active-color` | Active sort indicator |
| `--tbw-sort-indicator-display` | Sort indicator display |
| `--tbw-sort-indicator-visibility` | Sort indicator visibility |

### Shell & Panels

| Variable | Description |
| --- | --- |
| `--tbw-shell-header-height` | Shell header height |
| `--tbw-shell-header-bg` | Shell header background |
| `--tbw-shell-header-border` | Shell header border color |
| `--tbw-shell-title-font-size` | Shell title font size |
| `--tbw-shell-title-font-weight` | Shell title font weight |
| `--tbw-tool-panel-width` | Tool panel width |
| `--tbw-tool-panel-bg` | Tool panel background |
| `--tbw-tool-panel-border` | Tool panel border color |
| `--tbw-tool-panel-header-height` | Tool panel header height |
| `--tbw-tool-panel-transition` | Tool panel open/close transition |
| `--tbw-toolbar-button-size` | Toolbar button size |
| `--tbw-toolbar-button-gap` | Toolbar button gap |

### Component Shortcuts

| Variable | Description |
| --- | --- |
| `--tbw-panel-padding` | Panel content padding |
| `--tbw-panel-gap` | Panel content gap |
| `--tbw-menu-item-padding` | Menu item padding |
| `--tbw-menu-item-gap` | Menu item gap |
| `--tbw-menu-min-width` | Menu minimum width |
| `--tbw-button-padding` | Button padding |
| `--tbw-button-padding-sm` | Small button padding |
| `--tbw-input-height` | Input height |
| `--tbw-input-padding` | Input padding |
| `--tbw-detail-padding` | Detail row padding |
| `--tbw-detail-max-height` | Detail row max height |
| `--tbw-indicator-size` | Indicator dot size |

### Scrollbar

| Variable | Description |
| --- | --- |
| `--tbw-scrollbar-thumb` | Scrollbar thumb color |
| `--tbw-scrollbar-track` | Scrollbar track color |

### Loading Spinner

| Variable | Description |
| --- | --- |
| `--tbw-spinner-size` | Spinner size (grid-level) |
| `--tbw-spinner-border-width` | Spinner border thickness |
| `--tbw-spinner-color` | Spinner active color |
| `--tbw-spinner-track-color` | Spinner track color |

### Context Menu (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-context-menu-bg` | Context menu background |
| `--tbw-context-menu-fg` | Context menu text color |
| `--tbw-context-menu-border` | Context menu border color |
| `--tbw-context-menu-hover` | Context menu item hover |
| `--tbw-context-menu-muted` | Muted text (shortcuts) |
| `--tbw-context-menu-danger` | Danger action color |
| `--tbw-context-menu-radius` | Menu border radius |
| `--tbw-context-menu-shadow` | Menu box shadow |
| `--tbw-context-menu-min-width` | Minimum menu width |
| `--tbw-context-menu-font-size` | Menu font size |
| `--tbw-context-menu-font-family` | Menu font family |
| `--tbw-context-menu-item-padding` | Menu item padding |
| `--tbw-context-menu-item-gap` | Menu item gap |
| `--tbw-context-menu-icon-size` | Menu icon size |
| `--tbw-context-menu-shortcut-size` | Shortcut text size |
| `--tbw-context-menu-arrow-size` | Submenu arrow size |

### Filtering (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-filter-panel-bg` | Filter panel background |
| `--tbw-filter-panel-fg` | Filter panel text color |
| `--tbw-filter-panel-border` | Filter panel border |
| `--tbw-filter-panel-radius` | Filter panel radius |
| `--tbw-filter-panel-shadow` | Filter panel shadow color |
| `--tbw-filter-accent` | Filter accent color |
| `--tbw-filter-accent-fg` | Filter accent text color |
| `--tbw-filter-hover` | Filter item hover |
| `--tbw-filter-muted` | Filter muted text |
| `--tbw-filter-divider` | Filter divider color |
| `--tbw-filter-input-bg` | Filter input background |
| `--tbw-filter-input-border` | Filter input border color |
| `--tbw-filter-input-radius` | Filter input radius |
| `--tbw-filter-item-height` | Filter list item height |
| `--tbw-filter-search-padding` | Filter search input padding |
| `--tbw-filter-btn-padding` | Filter button padding |
| `--tbw-filter-btn-font-weight` | Filter button font weight |
| `--tbw-filter-btn-min-height` | Filter button min height |
| `--tbw-filter-btn-display` | Header filter button display |
| `--tbw-filter-btn-visibility` | Header filter button visibility |

### Selection (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-selection-border-style` | Selection border style |
| `--tbw-selection-border-width` | Selection border width |
| `--tbw-selection-warning-bg` | Invalid selection background |

### Editing (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-editing-bg` | Editing cell background |
| `--tbw-editing-row-bg` | Editing row background |
| `--tbw-editing-border` | Editor input border |
| `--tbw-padding-editing-input` | Editor input padding |
| `--tbw-font-size-editor` | Editor font size |
| `--tbw-editing-row-outline-color` | Editing row outline color |
| `--tbw-editing-row-outline-width` | Editing row outline width |
| `--tbw-invalid-bg` | Invalid cell background |
| `--tbw-invalid-border-color` | Invalid cell border color |

### Row Grouping (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-grouping-rows-bg` | Group row background |
| `--tbw-grouping-rows-bg-hover` | Group row hover bg |
| `--tbw-grouping-rows-toggle-hover` | Toggle button hover |
| `--tbw-grouping-rows-count-color` | Group count text color |
| `--tbw-grouping-rows-aggregate-color` | Aggregate value color |
| `--tbw-group-indent-width` | Group indent per level |

### Grouping Columns (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-grouping-columns-header-bg` | Column group header bg |
| `--tbw-grouping-columns-border` | Column group border |
| `--tbw-grouping-columns-separator` | Column group separator |

### Tree (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-tree-indent-width` | Tree indentation width |
| `--tbw-tree-toggle-size` | Tree toggle icon size |
| `--tbw-tree-accent` | Tree expand/collapse accent |

### Master-Detail (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-master-detail-bg` | Detail row background |
| `--tbw-master-detail-border` | Detail row border |

### Pivot (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-pivot-group-bg` | Pivot group row bg |
| `--tbw-pivot-group-hover` | Pivot group hover bg |
| `--tbw-pivot-leaf-bg` | Pivot leaf row bg |
| `--tbw-pivot-grand-total-bg` | Grand total row bg |
| `--tbw-pivot-toggle-size` | Pivot toggle icon size |
| `--tbw-pivot-toggle-color` | Pivot toggle color |
| `--tbw-pivot-toggle-hover-bg` | Pivot toggle hover bg |
| `--tbw-pivot-toggle-hover-color` | Pivot toggle hover color |
| `--tbw-pivot-count-color` | Pivot count text color |
| `--tbw-pivot-border` | Pivot section border |
| `--tbw-pivot-section-bg` | Pivot configurator bg |
| `--tbw-pivot-header-bg` | Pivot configurator header bg |
| `--tbw-pivot-drop-border` | Drop zone border |
| `--tbw-pivot-drop-bg` | Drop zone background |
| `--tbw-pivot-drop-active` | Active drop zone bg |
| `--tbw-pivot-chip-bg` | Pivot chip background |
| `--tbw-pivot-chip-border` | Pivot chip border |
| `--tbw-pivot-chip-hover` | Pivot chip hover bg |
| `--tbw-pivot-chip-remove-hover-bg` | Chip remove button hover bg |
| `--tbw-pivot-chip-remove-hover-fg` | Chip remove button hover text |

### Multi-Sort (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-multi-sort-badge-bg` | Sort badge background |
| `--tbw-multi-sort-badge-color` | Sort badge text color |
| `--tbw-multi-sort-badge-size` | Sort badge size |

### Visibility Panel (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-visibility-hover` | Visibility item hover |
| `--tbw-visibility-indicator` | Visibility indicator |
| `--tbw-visibility-border` | Visibility panel border |
| `--tbw-visibility-btn-bg` | Visibility button bg |

### Pinned Rows (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-pinned-rows-bg` | Pinned rows background |
| `--tbw-pinned-rows-border` | Pinned rows border |
| `--tbw-pinned-rows-color` | Pinned rows text color |
| `--tbw-aggregation-bg` | Aggregation row background |
| `--tbw-aggregation-border` | Aggregation row border |
| `--tbw-aggregation-font-size` | Aggregation font size |
| `--tbw-aggregation-font-weight` | Aggregation font weight |

### Responsive (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-responsive-duration` | Card layout transition |

### Print (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-print-border` | Print header border |
| `--tbw-print-muted` | Print muted text |
| `--tbw-print-cell-border` | Print cell border |

### Reorder Columns (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-reorder-indicator` | Column reorder indicator |

### Reorder Rows (Plugin)

| Variable | Description |
| --- | --- |
| `--tbw-row-reorder-handle-color` | Row drag handle color |
| `--tbw-row-reorder-handle-hover` | Row drag handle hover color |
| `--tbw-row-reorder-indicator` | Row reorder drop indicator |
| `--tbw-row-reorder-moving-bg` | Moving row background |
| `--tbw-row-reorder-moving-border` | Moving row border color |

### Z-Index Layers

| Variable | Description |
| --- | --- |
| `--tbw-z-layer-rows` | Row area z-index |
| `--tbw-z-layer-header` | Header z-index |
| `--tbw-z-layer-pinned-rows` | Pinned rows z-index |
| `--tbw-z-layer-toolpanel` | Tool panel z-index |

## Building a Custom Theme

Create a CSS file with your overrides:

```css
/* my-theme.css */
@layer tbw-theme {
  [data-tbw-grid],
  tbw-grid {
    --tbw-color-bg: #fafafa;
    --tbw-color-fg: #333;
    --tbw-color-border: #e0e0e0;
    --tbw-color-header-bg: #f5f5f5;
    --tbw-color-header-fg: #555;
    --tbw-color-row-hover: #e3f2fd;
    --tbw-color-accent: #1976d2;
    --tbw-color-focus-ring: #1976d2;
    --tbw-cell-padding: 0.4em 0.75em;
    --tbw-font-family: 'Inter', sans-serif;
  }
}
```

Import it **after** the grid:

```typescript
import '@toolbox-web/grid';
import './my-theme.css';
```

## Programmatic Styles

Since the grid uses **light DOM**, standard CSS works — global stylesheets, `<style>` in `<head>`, or external CSS files can all target elements inside `<tbw-grid>`.

For styles you need to inject or update **from JavaScript at runtime**, use the `registerStyles()` API:

```typescript
// Inject styles programmatically
grid.registerStyles('my-highlights', `
  .row-warning { background: #fff3e0; }
  .row-error { background: #fce4ec; }
`);

// Remove when no longer needed
grid.unregisterStyles('my-highlights');
```

:::caution
Do not place `<style>` elements as **children of `<tbw-grid>`** — the grid calls `replaceChildren()` during renders, which removes child nodes. This only applies to styles placed *inside* the grid element itself; external CSS is unaffected.
:::

## Plugin Styles

Plugins inject their own CSS via `adoptedStyleSheets` in the `tbw-plugins` cascade layer. You can override any plugin class in your theme:

| Plugin | Key CSS Classes | What They Style |
|--------|----------------|----------------|
| **Selection** | `.tbw-cell-selected`, `.tbw-row-selected` | Selected cells and rows highlight |
| **Editing** | `.tbw-cell-editing`, `.tbw-row-dirty`, `.tbw-row-new` | Active editor and dirty tracking indicators |
| **Filtering** | `.tbw-filter-active` | Filter icon active state |
| **Grouping** | `.tbw-group-row`, `.tbw-group-toggle`, `.tbw-row-expanded` | Group header rows, expand/collapse icons, expanded group |
| **Tree** | `.tbw-row-expanded` | Parent rows whose children are visible |
| **Master/Detail** | `.tbw-row-expanded` | Master rows whose detail panel is showing |
| **Responsive** | `.tbw-card-view`, `.tbw-card-row` | Card layout mode styling |

:::tip[Style expanded rows with `.tbw-row-expanded`, not `[aria-expanded]`]
Tree, GroupingRows, and MasterDetail all toggle `.tbw-row-expanded` on the row element when it is in an expanded state. Use this class for theming. The `aria-expanded` attribute is reserved for assistive technology and may move (MasterDetail puts it on the toggle button, not the row), so styling against `[aria-expanded="true"]` is fragile and framework-specific.
:::

Override in your theme:

```css
@layer tbw-theme {
  tbw-grid .tbw-cell-selected {
    background: rgba(25, 118, 210, 0.15);
  }
  tbw-grid .tbw-row-dirty {
    border-left: 3px solid orange;
  }
  tbw-grid .tbw-row-expanded {
    background: rgba(25, 118, 210, 0.05);
  }
}
```

## Icon Customization

The grid uses a **CSS-first hybrid icon system** with two configuration paths:

| Approach | Best for | How it works |
|----------|----------|-------------|
| **CSS variables** (default) | Themes, static icons, no-JS customization | Override `--tbw-icon-*` properties on `tbw-grid` |
| **JavaScript** (`gridConfig.icons`) | Dynamic icons, icon libraries, runtime changes | Set `icons` in grid config — takes precedence over CSS |

CSS is the **recommended default** — it requires no JavaScript, works with cascade layers, and is tree-shakeable. Use the JS path when you need dynamic icons (e.g., loading from an icon library at runtime) or `HTMLElement` instances.

For the full list of icon keys with their TypeScript signatures, see the [`GridIcons` interface](/grid/api/core/interfaces/gridicons.md).

### JavaScript Path (`gridConfig.icons`)

For programmatic control (e.g., dynamic icon libraries, `HTMLElement` icons, or runtime theme switching), use `gridConfig.icons`. JavaScript values take precedence over CSS variables:

```typescript
grid.gridConfig = {
  icons: {
    sortAsc: '↑',
    sortDesc: '↓',
    expand: '+',
    collapse: '−',
    // Values may also be HTMLElement instances for fully custom markup
  },
};
```

All grid icons (sort indicators, expand/collapse, filter, drag handles, etc.) are rendered via CSS custom properties. The remainder of this section covers the CSS-first approach — override them in your theme.

### Text / Emoji Icons

Set the `--tbw-icon-<key>` variable to any CSS `<string>` value:

```css
@layer tbw-theme {
  tbw-grid {
    --tbw-icon-sort-asc: '↑';
    --tbw-icon-sort-desc: '↓';
    --tbw-icon-expand: '+';
    --tbw-icon-collapse: '−';
    --tbw-icon-size: 1.2em;
  }
}
```

### SVG Mask Icons

The **filter** and **filter-active** icons use SVG masks by default — just override their `-mask` variable:

```css
@layer tbw-theme {
  tbw-grid {
    --tbw-icon-filter: '';
    --tbw-icon-filter-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z'/%3E%3C/svg%3E");
  }
}
```

For **any other icon**, switching to mask mode requires setting the content to `''`, providing a `-mask` URL, and adding `background: currentColor` with explicit dimensions:

```css
@layer tbw-theme {
  tbw-grid {
    /* Set content to '' and provide the mask URL */
    --tbw-icon-sort-asc: '';
    --tbw-icon-sort-asc-mask: url("data:image/svg+xml,...");
  }

  /* Add background + dimensions so the mask is visible (cannot be shipped
     generically because they would affect text/emoji icon layout) */
  tbw-grid [data-icon='sort-asc']:empty::before {
    width: var(--tbw-icon-size, 1em);
    height: var(--tbw-icon-size, 1em);
    background: currentColor;
  }
}
```

The grid ships `mask-image`, `mask-size`, `mask-repeat`, and `mask-position` for every icon — you only need to add `background: currentColor`.

### Available Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `--tbw-icon-expand` | `'▶'` | Tree / group / master-detail expand |
| `--tbw-icon-collapse` | `'▼'` | Tree / group / master-detail collapse |
| `--tbw-icon-sort-asc` | `'▲'` | Sort ascending indicator |
| `--tbw-icon-sort-desc` | `'▼'` | Sort descending indicator |
| `--tbw-icon-sort-none` | `'⇅'` | Unsorted indicator |
| `--tbw-icon-filter` | `''` (mask) | Column filter icon |
| `--tbw-icon-filter-active` | `''` (mask) | Active filter icon |
| `--tbw-icon-submenu-arrow` | `'▶'` | Context menu submenu arrow |
| `--tbw-icon-drag-handle` | `'⋮⋮'` | Row drag handle |
| `--tbw-icon-tool-panel` | `'☰'` | Tool panel toggle |
| `--tbw-icon-print` | `'🖨️'` | Print button |

Each icon also has a `-mask` variant (e.g., `--tbw-icon-sort-asc-mask`) for SVG mask-based rendering with `currentColor`.

## See Also

  - [Core Features](/grid/core.md): Column inference, renderers, row/cell styling, and animation
  - [Accessibility](/grid/guides/accessibility.md): High contrast mode and color requirements
  - [Architecture](/grid/architecture.md): CSS cascade layers and Light DOM design
  - [Responsive Plugin](/grid/plugins/responsive.md): Card layout mode with mobile-friendly responsive styling

---

# Troubleshooting

> Solutions to common issues when working with @toolbox-web/grid — height and virtualization problems, performance tuning, plugin conflicts, and framework adapter development.

The grid is designed to work out of the box with minimal setup. If you're hitting issues with basic configuration — TypeScript types, framework imports, or event handling — check the [Getting Started](/grid/getting-started.md) guide first, which covers setup for all frameworks.

This page covers two things: **how to debug the grid when something is wrong**, and the genuine gotchas that can't be solved in code alone.

---

## How to debug the grid

When the grid isn't doing what you expect, work through this checklist in order. Most issues fall out at one of the first three steps.

### 1. Read the console — every warning has a code

Every user-facing warning and error from the grid is prefixed with `[tbw-grid#<your-id>:<PluginName>]` and tagged with a stable diagnostic code (e.g. `TBW001`, `TBW020`). The code → cause mapping is published on the [Error Codes](/grid/errors.md) reference page.

```
[tbw-grid#employees:SelectionPlugin] TBW020 SelectionPlugin requires EditingPlugin
  when `editable` is set on any column. Add to your features:
  import '@toolbox-web/grid/features/editing';
```

What the parts mean:

| Part | Meaning |
|---|---|
| `[tbw-grid…]` | Came from the grid, not your app code |
| `#employees` | The grid's `id` attribute (or omitted if anonymous) — useful when you have several on a page |
| `:SelectionPlugin` | The plugin that produced the message (omitted for core messages) |
| `TBW020` | Stable code — links to [the errors page](/grid/errors.md) |

If a TBW code appears in production logs or a Sentry event, search the errors page first — most have an actionable fix one click away.

### 2. Inspect the grid's effective configuration

The biggest source of "why isn't this working?" confusion is *what config did the grid actually end up with*, after defaults, features, plugin merges, and light-DOM column nodes are all combined. The grid exposes the resolved config two ways:

```ts
import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('#employees');        // typed DataGridElement<T> — no casts needed
await grid.ready();                          // wait for first render

// Public — frozen, async, safe to assign from production code
const config = await grid.getConfig();
console.log(config);
console.log(config.plugins);

// Internal — synchronous getter, the live merged config. Great in the DevTools
// console; do NOT call from production code (see stability note below).
console.log(grid.effectiveConfig);
console.log(grid.effectiveConfig.plugins);

// Always-public state
console.log(grid.columns);                   // current column array (post-plugin transforms)
console.log(grid.rows);                      // current rows (post-sort/filter)
console.log(grid.sourceRows);                // unfiltered, unsorted source data
```

:::caution[Stability of internal APIs]
Anything documented below as **internal** (also: any property or method starting with `_` or `#` you find on the grid element) is reachable from the DevTools console but is **not covered by semver**. It can change or disappear in any release. Use it for debugging, logging, and one-off scripts — not for production code paths.
:::

Common things to check here:

- `config.plugins?.map(p => p.constructor.name)` — is the plugin you expect actually attached? Plugins are silently *not* added if their feature import was missed.
- `grid.columns` after assignment — did your inferred columns end up where you expected?
- `grid.rows.length` vs `grid.sourceRows.length` — does filtering/grouping account for the difference?
- `grid._pluginManager` *(internal)* — exposes the live plugin manager (lookup, ordering, hook subscriptions).
- `grid._virtualization` *(internal)* — current virtual window: `{ start, end, … }` — useful for "why isn't row N in the DOM?".

### 3. Find your grid (and a specific row/cell) in the DOM

The grid uses **Light DOM** — there's no shadow root to break inspection. Standard DevTools "Inspect element" works directly. The grid publishes its class names, data-attribute names, and prebuilt selectors as public constants so your queries don't break if internals change:

```ts
import { GridSelectors, GridClasses, GridDataAttrs, queryGrid } from '@toolbox-web/grid';

// Multi-version-safe grid lookup
const grid = queryGrid('#employees');
// Or any grid on the page (works across versions thanks to the data attribute):
queryGrid('[data-tbw-grid]');

// Use the published selectors — these are stable across versions
grid.querySelector(GridSelectors.HEADER_ROW);             // header row
grid.querySelectorAll(GridSelectors.DATA_ROW);            // all rendered data rows
grid.querySelectorAll(GridSelectors.DATA_CELL);           // all rendered cells
grid.querySelectorAll(GridSelectors.SELECTED_ROWS);       // selected rows
grid.querySelector(GridSelectors.EDITING_CELL);           // the currently-editing cell

// Find a specific cell by field, or by row index (data-row is on the cell)
grid.querySelector(GridSelectors.CELL_BY_FIELD('email')); // first cell in the 'email' column
grid.querySelector(`.${GridClasses.DATA_CELL}[data-row="42"][${GridDataAttrs.FIELD}="email"]`);
```

**Internal shortcuts** that are convenient in the DevTools console (subject to the stability note above):

```ts
grid.findHeaderRow();                        // the header row element
grid.findRenderedRowElement(42);             // null if row 42 is outside the virtualized window
grid._hostElement;                           // the grid root element
grid._renderRoot;                            // the inner render container
```

> **Virtualization gotcha:** at any moment the DOM only contains rows in the visible viewport + a small overscan buffer. If `grid.querySelectorAll(GridSelectors.DATA_ROW)` doesn't include the row you expect, it exists in `grid.rows` but hasn't been rendered yet — call `grid.scrollToRow(rowIndex)` (or `grid.scrollToRowById(rowId)`) to bring it into view, or operate on the data, not the DOM.

### 4. Watch what the grid is doing — listen to lifecycle events

Most "is the grid even re-rendering?" / "did my sort actually apply?" questions are answered in five seconds by attaching a listener. The full event catalog is exported as `DGEvents`:

```ts
import { DGEvents, PluginEvents } from '@toolbox-web/grid';

// Log every render (use the string literal — `render` is not in the legacy
// DGEvents enum because it was added later; the listener is type-checked
// against `DataGridEventMap`).
grid.on('render', (detail) => console.log('render', detail));

// Log every sort / filter / column / selection change
grid.on(DGEvents.SORT_CHANGE, (detail) => console.log('sort', detail));
grid.on(PluginEvents.FILTER_CHANGE, (detail) => console.log('filter', detail));
grid.on(DGEvents.COLUMN_STATE_CHANGE, (detail) => console.log('columns', detail));
grid.on(PluginEvents.SELECTION_CHANGE, (detail) => console.log('selection', detail));

// Log everything (catch-all — use briefly)
for (const name of [...Object.values(DGEvents), ...Object.values(PluginEvents)]) {
  grid.on(name, (detail) => console.log(name, detail));
}
```

`grid.on()` returns a disposer (`() => void`) — call it to stop listening. Useful patterns:

- **"My edit isn't saving"** → listen for `'cell-commit'` / `'row-commit'` and `'edit-close'`; see which one fires.
- **"My data appears stale"** → log `RENDER` after every data mutation; if it doesn't fire, the grid isn't seeing the change (most often: you mutated `rows` in place instead of assigning a new array).
- **"Selection state is wrong"** → log `SELECTION_CHANGE` to see what the grid thinks is selected.

### 5. Diagnose a hot path with the Performance tab

Anything that *works but is slow* is a performance question, not a config question. The [Performance guide](/grid/guides/performance.md#profile-your-own-app) has a flame-graph reading walkthrough that distinguishes grid-internal work from framework reconciliation from layout thrashing. Start there.

### 6. Diagnose a plugin

Plugin issues usually trace to one of three causes:

1. **Plugin not attached.** Confirm via `(await grid.getConfig()).plugins`. If your column uses `editable: true` and you see no `EditingPlugin` in the list, you forgot the feature import.
2. **Hook order conflict.** Two plugins manipulating the same columns/rows — see [Two plugins modifying the same columns/rows](#two-plugins-modifying-the-same-columnsrows).
3. **Hook too slow.** Plugin work in `afterCellRender` / `afterRowRender` shows up in the flame graph during scroll. See [Hook performance budget](/grid/plugin-development/architecture.md#hook-performance-budget).

When filing a plugin bug, include the output of:

```ts
const config = await grid.getConfig();
console.log(config.plugins?.map(p => ({
  name: p.constructor.name,
  config: p,
})));
```

### Quick reference: debug APIs

Stable APIs (covered by semver):

| API | Returns | Use when |
|---|---|---|
| `queryGrid(selector)` | grid element (or `null`) | Multi-version-safe lookup |
| `grid.ready()` | `Promise<void>` | Wait for first render before assertions |
| `grid.getConfig()` | `Promise<Readonly<GridConfig>>` | "What did the grid actually merge?" — async, frozen |
| `grid.columns` / `grid.rows` | current arrays | After-the-fact inspection |
| `grid.sourceRows` | unfiltered/unsorted data | Distinguish view from source |
| `grid.getRow(id)` / `grid.getRowId(row)` | row / string | Row identity debugging |
| `grid.on(name, listener)` | disposer | Watch what the grid is doing |
| `DGEvents` / `PluginEvents` | event-name catalog | "What can I even listen for?" |
| `GridSelectors` / `GridClasses` / `GridDataAttrs` | stable selectors and attribute names | Standard DOM queries against the grid |
| `grid.scrollToRow(index)` / `grid.scrollToRowById(id)` | `void` | Bring a virtualized row into view |
| `grid.forceLayout()` | `Promise<void>` | Re-measure after content change |

Internal helpers (reachable from the DevTools console — not covered by semver):

| API | Returns | Use when |
|---|---|---|
| `grid.effectiveConfig` | `GridConfig` (sync, live) | Quick sync peek at merged config from the console |
| `grid.findHeaderRow()` | `HTMLElement` | Direct header lookup |
| `grid.findRenderedRowElement(index)` | element or `null` | DOM lookup respecting virtualization |
| `grid._pluginManager` | `PluginManager` | Inspect plugin ordering, hook subscriptions |
| `grid._virtualization` | `{ start, end, … }` | See the current virtual window |
| `grid._hostElement` / `grid._renderRoot` | `HTMLElement` | Direct internal DOM access |
| `grid.disconnectSignal` | `AbortSignal` | Auto-cleanup for ad-hoc listeners |

---

## Height & Virtualization

The grid virtualizes rows for performance, which requires a **constrained height**. This is the most common setup issue.

### Grid appears empty or collapsed

The grid needs an explicit height. Without one, the container collapses to zero and nothing renders.

```css
/* ✅ Fixed height */
tbw-grid {
  height: 500px;
}

/* ✅ Flex layout */
.container {
  display: flex;
  flex-direction: column;
  height: 100vh;
}
tbw-grid {
  flex: 1;
  min-height: 0; /* Required for flex children to shrink */
}
```

If you don't need virtual scrolling (small datasets), set `height: auto` so the grid sizes to its content:

```css
tbw-grid {
  height: auto;
}
```

### Rows appear in wrong positions after scroll

Variable row heights can cause position drift. Use a fixed `rowHeight` for best accuracy:

```typescript
grid.gridConfig = { rowHeight: 36 };
```

If you need auto-measured heights, call `forceLayout()` after content changes:

```typescript
await grid.forceLayout();
```

### Blank rows or flickering during fast scroll

The grid renders a buffer of extra rows (overscan) above and below the viewport. During very fast scrolling, the buffer can be exhausted before new rows paint. Setting `rowHeight` explicitly lets the grid calculate positions without measuring, which keeps up better:

```typescript
grid.gridConfig = { rowHeight: 32 };
```

---

## Performance

### Use formatters over renderers for simple values

`format` returns a string — significantly faster than creating DOM elements in a `renderer`:

```typescript
// ✅ Fast — string formatter
{ field: 'salary', format: (v) => `$${v.toLocaleString()}` }

// ⚠️ Slower — DOM renderer (use only when you need rich content)
{ field: 'salary', renderer: (ctx) => {
  const el = document.createElement('span');
  el.textContent = `$${ctx.value.toLocaleString()}`;
  return el;
}}
```

### Column virtualization for wide grids

For 50+ columns, enable the `columnVirtualization` feature so off-screen columns aren't rendered:

```typescript
import '@toolbox-web/grid/features/column-virtualization';

grid.gridConfig = {
  features: { columnVirtualization: true },
};
```

### Disable animations during initial load

If first paint feels slow, disable animations:

```typescript
grid.gridConfig = { animation: { mode: 'off' } };
```

See the [Performance Guide](/grid/guides/performance.md) for profiling techniques and detailed tuning.

---

## For Plugin & Adapter Developers

The sections below cover issues specific to **custom plugin** and **framework adapter** development.

### Plugin dependency errors

A plugin requires another plugin that isn't loaded:

```
UndoRedoPlugin requires EditingPlugin
```

**Fix with features API** (auto-resolves dependencies):

```typescript
import '@toolbox-web/grid/features/undo-redo';
// EditingPlugin is loaded automatically
```

**Fix with plugins API** (manual ordering):

```typescript
plugins: [
  new EditingPlugin(),     // Must come first
  new UndoRedoPlugin(),    // Depends on EditingPlugin
]
```

### Two plugins modifying the same columns/rows

**Symptoms**: Unexpected column order, missing columns, or data appearing twice.

Plugins process columns and rows in registration order. If two plugins manipulate the same columns, they may conflict. When using the features API, try reordering the `features` entries. When using the plugins API, reorder the array — the last plugin to process wins.

### Known plugin incompatibilities

| Plugin A | Plugin B | Issue |
|----------|----------|-------|
| GroupingRowsPlugin | TreePlugin | Both transform the entire row model |
| GroupingRowsPlugin | PivotPlugin | Pivot creates its own row/column structure |
| TreePlugin | PivotPlugin | Pivot replaces the data structure |
| ServerSidePlugin | GroupingRows/Tree/Pivot | These require the full dataset; server-side loads lazily |

See the [Plugins Overview → Known Incompatibilities](/grid/plugins.md#known-incompatibilities) for the full list.

### Styles not applying (CSP)

The grid injects plugin styles via `adoptedStyleSheets`. If your CSP blocks this, styles fail silently.

**Required CSP header:**

```
style-src 'self';
```

`adoptedStyleSheets` does not require `'unsafe-inline'` — it's treated as a programmatic stylesheet. Check the browser console for CSP violation messages.

### CSS cascade layer specificity

The grid's built-in styles use CSS `@layer`. Your custom CSS may not be specific enough to override them.

**Use CSS custom properties** (recommended):

```css
tbw-grid {
  --tbw-color-row-hover: #e0f7fa;
  --tbw-cell-padding: 12px 16px;
}
```

Since the grid uses Light DOM, normal CSS selectors also work — just ensure your selectors are specific enough to beat the `@layer` defaults.

---

## Still Stuck?

If you've worked through [How to debug the grid](#how-to-debug-the-grid) and the issue isn't covered above, the fastest path to help is a minimal reproduction:

1. **Strip your code to the smallest example that still reproduces the issue** — one grid, the minimum config, ideally in a [StackBlitz](https://stackblitz.com/) or a single HTML file with the UMD bundle.
2. **Capture the diagnostic output** — copy the TBW error code and full prefixed message from the console.
3. **Capture the effective config** — `console.log(await grid.getConfig())` and include the plugin list.
4. **Search [existing GitHub issues](https://github.com/OysteinAmundsen/toolbox/issues)** — someone may have hit the same wall.
5. **Open a new issue** with reproduction, browser/OS, grid version, and the captures above.

## See Also

  - [Getting Started](/grid/getting-started.md): Installation and setup for all frameworks
  - [Automated testing](/grid/guides/automated-testing.md): Drive the grid from Playwright, Cypress, or WebdriverIO
  - [Performance Guide](/grid/guides/performance.md): Profiling, virtualization tuning, and bundle optimization
  - [Production Checklist](/grid/guides/production-checklist.md): Security, performance, and deployment readiness
  - [Custom Plugins](/grid/plugin-development/custom-plugins.md): Plugin development guide — hooks, styles, lifecycle
  - [Plugins Overview](/grid/plugins.md): Plugin compatibility, dependencies, and known conflicts

---

# Clipboard Plugin

> Copy and paste grid data with Excel-compatible clipboard support.

The Clipboard plugin brings familiar copy/paste functionality to your grid with full keyboard shortcut support (Ctrl+C, Ctrl+V). It handles single cells, multi-cell selections, and integrates seamlessly with Excel and other spreadsheet applications via tab-delimited output.

:::tip
Works best with [SelectionPlugin](/grid/plugins/selection.md) for copying/pasting selected cells. Without it, copies the entire grid and pastes at row 0, column 0.
:::

## Installation

```ts
import '@toolbox-web/grid/features/clipboard';
```

## Basic Usage

Just enable the feature and you're ready to go—keyboard shortcuts work automatically. Configure options like `includeHeaders` for copying column headers or `delimiter` for custom CSV formats.

#### Angular

```typescript
// Feature imports - enable the [selection] and [clipboard] inputs
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
import { GridClipboardDirective } from '@toolbox-web/grid-angular/features/clipboard';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridSelectionDirective, GridClipboardDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [selection]="'range'"
      [clipboard]="{ includeHeaders: true, quoteStrings: true }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [...];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' }
  ];
}
```

## Demos

### Default Clipboard

```ts
// ClipboardDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/clipboard';
import '@toolbox-web/grid/features/selection';

const container = document.getElementById('clipboard-default-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice', email: 'alice@example.com', department: 'Engineering' },
    { id: 2, name: 'Bob', email: 'bob@example.com', department: 'Marketing' },
    { id: 3, name: 'Carol', email: 'carol@example.com', department: 'Engineering' },
    { id: 4, name: 'Dan', email: 'dan@example.com', department: 'Sales' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(includeHeaders = false, quoteStrings = false) {
    grid.gridConfig = {
      columns,
      features: {
        selection: 'range',
        clipboard: { includeHeaders, quoteStrings },
      },
    };
    grid.rows = sampleData;
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    const v = e.detail.allValues;
    rebuild(v.includeHeaders as boolean, v.quoteStrings as boolean);
  }) as EventListener);
}
```

Select cells and use Ctrl+C to copy, Ctrl+V to paste.

### Copy & Paste (Auto-Paste)

```ts
// ClipboardCopyPasteDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/clipboard';
import '@toolbox-web/grid/features/editing';
import '@toolbox-web/grid/features/selection';

const container = document.getElementById('clipboard-copy-paste-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'col1', header: 'Column 1', editable: true },
      { field: 'col2', header: 'Column 2', editable: true },
      { field: 'col3', header: 'Column 3', editable: true },
    ],
    features: {
      selection: 'range',
      clipboard: true,
      editing: true,
    },
  };

  grid.rows = [
    { col1: 'A1', col2: 'B1', col3: 'C1' },
    { col1: 'A2', col2: 'B2', col3: 'C2' },
    { col1: 'A3', col2: 'B3', col3: 'C3' },
    { col1: 'A4', col2: 'B4', col3: 'C4' },
  ];
}
```

By default, the ClipboardPlugin handles paste operations automatically—no event handling needed.
Just add the plugin and paste works out of the box.

### Custom Paste Handler

```ts
// ClipboardCustomPasteHandlerDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/clipboard';
import '@toolbox-web/grid/features/selection';

const container = document.getElementById('clipboard-custom-paste-handler-demo');
if (container) {
  // Sample data for clipboard demos
  const sampleData = [
    { id: 1, name: 'Alice', email: 'alice@example.com', department: 'Engineering' },
    { id: 2, name: 'Bob', email: 'bob@example.com', department: 'Marketing' },
    { id: 3, name: 'Carol', email: 'carol@example.com', department: 'Engineering' },
    { id: 4, name: 'Dan', email: 'dan@example.com', department: 'Sales' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
  ];

  // Sample data to copy
      const sampleDataBox = document.createElement('div');
      sampleDataBox.style.cssText = `
        padding: 12px;
        background: var(--demo-sample-bg);
        border-bottom: 1px solid var(--demo-sample-border);
        font-family: monospace;
        font-size: 13px;
        white-space: pre;
        user-select: all;
        cursor: text;
      `;
      sampleDataBox.textContent = `hello\tworld
  foo\tbar`;
      sampleDataBox.title = 'Paste this into the grid - values will be uppercased!';

      // Instructions banner
      const banner = document.createElement('div');
      banner.style.cssText = `
        padding: 12px;
        background: var(--demo-info-bg);
        border-bottom: 1px solid var(--demo-info-border);
        font-size: 14px;
        color: var(--demo-info-fg);
      `;
      banner.innerHTML = `
        <strong>Custom Handler:</strong> Pasted values are automatically UPPERCASED.
        <br>This demo also prevents adding new rows when pasting beyond the grid.
      `;

      // Grid
      const grid = queryGrid('tbw-grid', container);
      grid.style.cssText = 'flex: 1;';

      // Custom paste handler that uppercases values and prevents adding rows
      const customPasteHandler = (detail, gridEl) => {
        if (!detail.target) return;

        const { rows: pastedRows, target, fields } = detail;
        const columns = gridEl.effectiveConfig.columns ?? [];
        const allFields = columns.map((c) => c.field);
        const currentRows = [...(gridEl.rows as Record<string, string>[])];

        pastedRows.forEach((rowData, rowOffset) => {
          const targetRowIndex = target.row + rowOffset;

          // This handler allows adding rows (unlike the code sample which doesn't)
          while (targetRowIndex >= currentRows.length) {
            const emptyRow = {};
            allFields.forEach((f) => (emptyRow[f] = ''));
            currentRows.push(emptyRow);
          }

          currentRows[targetRowIndex] = { ...currentRows[targetRowIndex] };
          rowData.forEach((value, colOffset) => {
            const field = fields[colOffset];
            if (field) {
              // Transform: uppercase all values
              currentRows[targetRowIndex][field] = value.toUpperCase();
            }
          });
        });

        gridEl.rows = currentRows;
      };

      grid.gridConfig = {
        columns: [
          { field: 'col1', header: 'Column 1' },
          { field: 'col2', header: 'Column 2' },
          { field: 'col3', header: 'Column 3' },
        ],
        features: {
          selection: 'range',
          clipboard: { pasteHandler: customPasteHandler },
        },
      };

      grid.rows = [
        { col1: 'A1', col2: 'B1', col3: 'C1' },
        { col1: 'A2', col2: 'B2', col3: 'C2' },
        { col1: 'A3', col2: 'B3', col3: 'C3' },
      ];
}
```

For advanced use cases, provide a custom `pasteHandler` to validate, transform, or integrate with state management.

### Single Cell Mode

```ts
// ClipboardSingleCellModeDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/clipboard';

const container = document.getElementById('clipboard-single-cell-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 60 },
      { field: 'name', header: 'Name' },
      { field: 'department', header: 'Department' },
      { field: 'email', header: 'Email' },
      { field: 'salary', header: 'Salary', type: 'number', align: 'right' },
    ],
    features: { clipboard: true },
  };

  grid.rows = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', email: 'alice@company.com', salary: 85000 },
    { id: 2, name: 'Bob Smith', department: 'Marketing', email: 'bob@company.com', salary: 72000 },
    { id: 3, name: 'Carol Williams', department: 'Engineering', email: 'carol@company.com', salary: 92000 },
    { id: 4, name: 'David Brown', department: 'Sales', email: 'david@company.com', salary: 68000 },
    { id: 5, name: 'Emma Davis', department: 'HR', email: 'emma@company.com', salary: 65000 },
    { id: 6, name: 'Frank Miller', department: 'Engineering', email: 'frank@company.com', salary: 88000 },
  ];
}
```

Without a SelectionPlugin, the clipboard operates on a single focused cell — press <kbd>Ctrl+C</kbd> to copy just that cell's value.

## Configuration Options

| Option           | Type                                  | Default              | Description                                                                                              |
| ---------------- | ------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------- |
| `includeHeaders` | `boolean`                             | `false`              | Include column headers in copied data                                                                    |
| `delimiter`      | `string`                              | `'\t'`               | Column delimiter (tab for Excel compatibility)                                                           |
| `newline`        | `string`                              | `'\n'`               | Row delimiter                                                                                            |
| `quoteStrings`   | `boolean`                             | `false`              | Wrap string values in quotes                                                                             |
| `processCell`    | `(value, field, row) => string`       | -                    | Custom cell value processor for copy operations                                                          |
| `pasteHandler`   | `PasteHandler \| null`                | `defaultPasteHandler`| Custom paste handler. Set to `null` to disable auto-paste and handle the `paste` event manually         |

## Paste Behavior

The clipboard plugin respects both selection bounds and the `editable` column property when pasting:

### Editable Columns

**Paste only works on columns marked `editable: true`.** Non-editable columns are skipped during paste, preserving column alignment:

```ts
columns: [
  { field: 'id', header: 'ID' },                    // NOT editable - paste skipped
  { field: 'name', header: 'Name', editable: true }, // Paste allowed
  { field: 'email', header: 'Email', editable: true }, // Paste allowed
]
```

If you paste `"1\t2\t3"` into this grid, only the `name` and `email` columns receive values (`2` and `3`). The `id` column remains unchanged.

:::tip
This works independently of the EditingPlugin. You can use `editable: true` to control paste behavior even without enabling inline editing.
:::

### Selection Bounds

| Selection Type  | Paste Behavior                                                                 |
| --------------- | ------------------------------------------------------------------------------ |
| Single cell     | Paste expands freely from that cell, adding rows if needed                     |
| Range selection | Paste is clipped to fit within the selected range                              |
| Row selection   | Paste is clipped to the selected rows (all columns within those rows)          |
| No selection    | Paste starts at row 0, column 0                                                |

**Example:** If you have a 2×2 range selected and paste 3×3 data, only the 2×2 portion that fits will be applied.

## Keyboard Shortcuts

| Shortcut           | Action                    |
| ------------------ | ------------------------- |
| `Ctrl+C` / `Cmd+C` | Copy selected cells       |
| `Ctrl+V` / `Cmd+V` | Paste into selected cells |

## Programmatic API

The ClipboardPlugin exposes methods for programmatic copy operations with fine-grained control over which columns and rows to include. This is ideal for workflows where users select rows in the grid, then choose columns via a dialog before copying.

### Basic Copy

```ts
const plugin = grid.getPluginByName('clipboard');

// Copy current selection to clipboard
await plugin.copy();

// Copy with headers included
await plugin.copy({ includeHeaders: true });
```

### Copy with Column/Row Control (`CopyOptions`)

The `copy()` method accepts `CopyOptions` to precisely control what gets copied—independently of the current selection:

```ts
const plugin = grid.getPluginByName('clipboard');

// Copy specific columns from specific rows
await plugin.copy({
  rowIndices: [0, 3, 7],         // Non-contiguous rows supported
  columns: ['name', 'email'],    // Only these columns
  includeHeaders: true,
});

// Copy specific rows with all visible columns
await plugin.copyRows([0, 5]);

// Copy specific rows with column filter
await plugin.copyRows([0, 5], { columns: ['name', 'department'] });
```

### Preview Without Copying

Use `getSelectionAsText()` to get the formatted text without writing to the clipboard—useful for preview dialogs:

```ts
const text = plugin.getSelectionAsText({
  columns: ['name', 'email', 'department'],
  includeHeaders: true,
});
// "Name\tEmail\tDepartment\nAlice\talice@example.com\tEngineering\n..."
```

### `CopyOptions` Reference

| Option           | Type                            | Default       | Description                                        |
| ---------------- | ------------------------------- | ------------- | -------------------------------------------------- |
| `columns`        | `string[]`                      | -             | Specific column fields to include                  |
| `rowIndices`     | `number[]`                      | -             | Specific row indices to copy (non-contiguous OK)   |
| `includeHeaders` | `boolean`                       | config value  | Include column headers in copied text              |
| `delimiter`      | `string`                        | config value  | Column delimiter override                          |
| `newline`        | `string`                        | config value  | Row delimiter override                             |
| `processCell`    | `(value, field, row) => string` | config value  | Custom cell value processor for this operation     |

### Paste

```ts
// Paste from clipboard
await plugin.paste();

// Get last copied info
const lastCopied = plugin.getLastCopied();
// { text: '...', timestamp: 1234567890 }
```

## Excel Compatibility

The default tab delimiter ensures copied data pastes correctly into Excel:

```ts
features: {
  clipboard: {
    delimiter: '\t', // Tab for Excel
    includeHeaders: true, // Include column names
  },
},
```

## Events

| Event   | Detail                                     | Description                   |
| ------- | ------------------------------------------ | ----------------------------- |
| `copy`  | `{ text, rowCount, columnCount }`          | Fired after cells are copied  |
| `paste` | `{ rows, text, target, fields }`           | Fired after data is pasted    |

## Styling

The clipboard plugin doesn't add visible UI elements. Selection styling is handled by the SelectionPlugin.

## See Also

- [Selection](/grid/plugins/selection.md) — Cell and row selection
- [Editing](/grid/plugins/editing.md) — Inline cell editing
- [Export](/grid/plugins/export.md) — Export to CSV/JSON

---

# Column Virtualization Plugin

> Improve performance for grids with many columns by only rendering visible columns.

The Column Virtualization plugin improves performance for grids with many columns.

## Installation

```ts
import '@toolbox-web/grid/features/column-virtualization';
```

## Basic Usage

#### Angular

```typescript
// Feature import - enables the [columnVirtualization] input
import { GridColumnVirtualizationDirective } from '@toolbox-web/grid-angular/features/column-virtualization';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-wide-grid',
  imports: [Grid, GridColumnVirtualizationDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [columnVirtualization]="true"
      fitMode="fixed"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class WideGridComponent {
  rows = [...];
  columns: ColumnConfig[] = this.generateManyColumns(100);

  generateManyColumns(count: number): ColumnConfig[] {
    return Array.from({ length: count }, (_, i) => ({
      field: `col${i}`,
      header: `Column ${i + 1}`,
      width: 120,
    }));
  }
}
```

## Demos

### Default Column Virtualization

```ts
// ColumnVirtualizationDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/column-virtualization';

const container = document.getElementById('column-virtualization-default-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container)!;

  function generateColumns(count: number) {
    const columns = [{ field: 'id', header: 'ID', type: 'number' as const, width: 60 }];
    for (let i = 1; i < count; i++) {
      columns.push({ field: `col${i}`, header: `Column ${i}`, type: 'number' as const, width: 100 });
    }
    return columns;
  }

  function generateRows(rowCount: number, colCount: number) {
    const rows = [];
    for (let r = 0; r < rowCount; r++) {
      const row: Record<string, number> = { id: r + 1 };
      for (let c = 1; c < colCount; c++) {
        row[`col${c}`] = Math.floor(Math.random() * 1000);
      }
      rows.push(row);
    }
    return rows;
  }

  function rebuild(columnCount = 50, threshold = 30, overscan = 3, autoEnable = true) {
    const columns = generateColumns(columnCount);
    const rows = generateRows(100, columnCount);
    grid.gridConfig = {
      columns,
      fitMode: 'fixed',
      features: { columnVirtualization: { autoEnable, threshold, overscan } },
    };
    grid.rows = rows;
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    const v = e.detail.allValues;
    rebuild(v.columnCount as number, v.threshold as number, v.overscan as number, v.autoEnable as boolean);
  }) as EventListener);
}
```

Use the **Column Count** slider to add up to 1000 columns, and toggle **Auto Enable** to compare performance with and without virtualization.

## Configuration Options

| Option       | Type      | Default | Description                 |
| ------------ | --------- | ------- | --------------------------- |
| `autoEnable` | `boolean` | `true`  | Auto-enable above threshold |
| `threshold`  | `number`  | `30`    | Column count threshold      |
| `overscan`   | `number`  | `3`     | Extra columns to render     |

## Requirements

- `fitMode: 'fixed'` — the plugin is designed for fixed-width column layouts
- Columns should have explicit widths (columns without widths default to 100px)

## Programmatic API

```ts
const plugin = grid.getPluginByName('columnVirtualization');

// Check if virtualization is currently active
const active = plugin.getIsVirtualized();

// Get the visible column index range
const { start, end } = plugin.getVisibleColumnRange();

// Scroll a specific column into view
plugin.scrollToColumn(42);
```

## See Also

- **[Performance](/grid/guides/performance.md)** — Performance optimization tips
- **[Pinned Columns](/grid/plugins/pinned-columns.md)** — Sticky columns (excluded from virtualization)

---

# Context Menu Plugin

> Add right-click context menus to the grid with customizable items.

The Context Menu plugin adds a customizable right-click menu to your grid cells. Build anything from simple copy/paste actions to complex nested menus with conditional visibility, icons, and keyboard shortcuts.

## Installation

```ts
import '@toolbox-web/grid/features/context-menu';
```

## Basic Usage

Define your menu items as an array—each item has an `id`, `label`, and `action` callback that receives context about the clicked cell (row data, column info, cell value, etc.). Add separators between groups of actions for visual clarity.

#### Angular

```typescript
// Feature import - enables the [contextMenu] input
import { GridContextMenuDirective } from '@toolbox-web/grid-angular/features/context-menu';
import { Component, output } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';
import type { ContextMenuItem } from '@toolbox-web/grid/plugins/context-menu';

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridContextMenuDirective],
  template: `
    <tbw-grid
      #grid
      [rows]="rows"
      [columns]="columns"
      [contextMenu]="contextMenuConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  deleteRow = output<number>();
  rows = [...];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'status', header: 'Status' }
  ];

  contextMenuConfig = {
    items: [
      { id: 'copy', name: 'Copy Cell', action: (ctx: any) => navigator.clipboard.writeText(String(ctx.value)) },
      { id: 'sep1', name: '', separator: true },
      { id: 'delete', name: 'Delete Row', action: (ctx: any) => this.deleteRow.emit(ctx.rowIndex) },
    ] as ContextMenuItem[],
  };
}
```

## Demos

### Default Context Menu

```ts
// ContextMenuDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import type { ContextMenuParams } from '@toolbox-web/grid/plugins/context-menu';
import '@toolbox-web/grid/features/context-menu';

const container = document.getElementById('context-menu-default-demo');
if (container) {
  // Sample data for context menu demos
  const sampleData = [
    { id: 1, name: 'Alice', email: 'alice@example.com', status: 'active' },
    { id: 2, name: 'Bob', email: 'bob@example.com', status: 'pending' },
    { id: 3, name: 'Carol', email: 'carol@example.com', status: 'active' },
    { id: 4, name: 'Dan', email: 'dan@example.com', status: 'inactive' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'status', header: 'Status' },
  ];
  // Default menu items
  const defaultMenuItems = [
    {
      id: 'copy',
      name: 'Copy Row',
      icon: '📋',
      shortcut: 'Ctrl+C',
      action: (params: ContextMenuParams) => console.log('Copy', params.row),
    },
    { id: 'edit', name: 'Edit Row', icon: '✏️', action: (params: ContextMenuParams) => console.log('Edit', params.row) },
    { id: 'sep1', name: '', separator: true },
    {
      id: 'duplicate',
      name: 'Duplicate',
      icon: '📄',
      action: (params: ContextMenuParams) => console.log('Duplicate', params.row),
    },
    { id: 'sep2', name: '', separator: true },
    {
      id: 'delete',
      name: 'Delete',
      icon: '🗑️',
      cssClass: 'danger',
      action: (params: ContextMenuParams) => console.log('Delete', params.row),
    },
  ];

  const grid = queryGrid('tbw-grid', container);

      grid.gridConfig = {
        columns,
        features: { contextMenu: { items: defaultMenuItems } },
      };
      grid.rows = sampleData;
}
```

Right-click any cell to see the context menu.

### With Submenus

```ts
// ContextMenuWithSubmenusDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/context-menu';

const container = document.getElementById('context-menu-with-submenus-demo');
if (container) {
  // Sample data for context menu demos
  const sampleData = [
    { id: 1, name: 'Alice', email: 'alice@example.com', status: 'active' },
    { id: 2, name: 'Bob', email: 'bob@example.com', status: 'pending' },
    { id: 3, name: 'Carol', email: 'carol@example.com', status: 'active' },
    { id: 4, name: 'Dan', email: 'dan@example.com', status: 'inactive' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'status', header: 'Status' },
  ];
  const grid = queryGrid('tbw-grid', container);

      const menuItems = [
        { id: 'view', name: 'View', icon: '👁️', action: () => console.log('View') },
        { id: 'edit', name: 'Edit', icon: '✏️', action: () => console.log('Edit') },
        { id: 'sep1', name: '', separator: true },
        {
          id: 'export',
          name: 'Export',
          icon: '📤',
          subMenu: [
            { id: 'csv', name: 'As CSV', action: () => console.log('Export CSV') },
            { id: 'json', name: 'As JSON', action: () => console.log('Export JSON') },
            { id: 'excel', name: 'As Excel', action: () => console.log('Export Excel') },
          ],
        },
        {
          id: 'share',
          name: 'Share',
          icon: '🔗',
          subMenu: [
            { id: 'email', name: 'Email', icon: '📧', action: () => console.log('Share Email') },
            { id: 'slack', name: 'Slack', icon: '💬', action: () => console.log('Share Slack') },
          ],
        },
      ];

      grid.gridConfig = {
        columns,
        features: { contextMenu: { items: menuItems } },
      };
      grid.rows = sampleData;
}
```

Nested menu items for complex actions.

### Conditional Items

```ts
// ContextMenuConditionalItemsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/context-menu';

const container = document.getElementById('context-menu-conditional-items-demo');
if (container) {
  // Sample data for context menu demos
  const sampleData = [
    { id: 1, name: 'Alice', email: 'alice@example.com', status: 'active' },
    { id: 2, name: 'Bob', email: 'bob@example.com', status: 'pending' },
    { id: 3, name: 'Carol', email: 'carol@example.com', status: 'active' },
    { id: 4, name: 'Dan', email: 'dan@example.com', status: 'inactive' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'status', header: 'Status' },
  ];
  const grid = queryGrid('tbw-grid', container);

      const menuItems = [
        {
          id: 'activate',
          name: 'Activate',
          icon: '✅',
          disabled: (params) => (params.row as { status?: string })?.status === 'active',
          action: (p) => console.log('Activate', p.row),
        },
        {
          id: 'deactivate',
          name: 'Deactivate',
          icon: '⏸️',
          disabled: (params) => (params.row as { status?: string })?.status !== 'active',
          action: (p) => console.log('Deactivate', p.row),
        },
        { id: 'sep1', name: '', separator: true },
        { id: 'delete', name: 'Delete', icon: '🗑️', cssClass: 'danger', action: (p) => console.log('Delete', p.row) },
      ];

      grid.gridConfig = {
        columns,
        features: { contextMenu: { items: menuItems } },
      };
      grid.rows = sampleData;
}
```

Show/hide items based on context.

### Plugin-Contributed Items

```ts
// PluginContributedItemsDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/context-menu';
import '@toolbox-web/grid/features/filtering';
import '@toolbox-web/grid/features/pinned-columns';
import '@toolbox-web/grid/features/visibility';

  const grid = queryGrid('#demo-context-menu-plugin-items');
  if (grid) {
    grid.gridConfig = {
      columns: [
        { field: 'id', header: 'ID', type: 'number', width: 80 },
        { field: 'name', header: 'Name', sortable: true },
        { field: 'email', header: 'Email', sortable: true },
        { field: 'status', header: 'Status', sortable: true },
      ],
      features: {
        filtering: true,
        visibility: true,
        pinnedColumns: true,
        contextMenu: {
          items: [
            {
              id: 'copy-row',
              name: 'Copy Row',
              icon: '📋',
              action: (params) => {
                console.log('Copy row:', params.row);
              },
            },
            {
              id: 'highlight',
              name: 'Highlight Row',
              icon: '🔆',
              action: (params) => {
                const rowEl = params.rowElement;
                if (rowEl) {
                  rowEl.style.background = 'light-dark(#fff3cd, #4a3f00)';
                  setTimeout(() => { rowEl.style.background = ''; }, 2000);
                }
              },
            },
          ],
        },
      },
    };

    grid.rows = [
      { id: 1, name: 'Alice Johnson', email: 'alice@example.com', status: 'active' },
      { id: 2, name: 'Bob Smith', email: 'bob@example.com', status: 'pending' },
      { id: 3, name: 'Carol Davis', email: 'carol@example.com', status: 'active' },
      { id: 4, name: 'Dan Wilson', email: 'dan@example.com', status: 'inactive' },
      { id: 5, name: 'Eve Brown', email: 'eve@example.com', status: 'active' },
      { id: 6, name: 'Frank Miller', email: 'frank@example.com', status: 'pending' },
    ];
  }
```

Plugins like FilteringPlugin, VisibilityPlugin, and PinnedColumnsPlugin can contribute their own items to the context menu automatically.

## Configuration Options

| Option  | Type         | Default | Description           |
| ------- | ------------ | ------- | --------------------- |
| `items` | `ContextMenuItem[]` | Copy + Export CSV | Menu items to display |

## TypeScript Interfaces

- [`ContextMenuItem`](/grid/plugins/context-menu/interfaces/contextmenuitem.md) — Menu item definition (id, label, icon, action, submenus, etc.)
- [`ContextMenuParams`](/grid/plugins/context-menu/interfaces/contextmenuparams.md) — Context passed to action callbacks (row, column, value, selection, etc.)
- [`ContextMenuConfig`](/grid/plugins/context-menu/interfaces/contextmenuconfig.md) — Plugin configuration options

### Selection Sync

When used with the `SelectionPlugin` (row mode), the context menu automatically syncs
the selection on right-click:

| Scenario | Behavior |
|----------|----------|
| Right-click a selected row | Multi-selection preserved |
| Right-click an unselected row | Selects only that row |
| No SelectionPlugin loaded | `selectedRows` = `[rowIndex]` |
| Right-click on header | `selectedRows` = `[]` |

This uses the **plugin query system** for loose coupling — no hard dependency on `SelectionPlugin`.

## Conditional Items

```ts
features: {
  contextMenu: {
    items: [
      {
        id: 'edit',
        name: 'Edit',
        hidden: (params) => params.column.editable !== true,
      },
      {
        id: 'delete',
        name: 'Delete',
        disabled: (params) => params.row.locked === true,
      },
    ],
  },
},
```

## Events

| Event               | Detail              | Description |
| ------------------- | ------------------- | ----------- |
| `context-menu-open` | `{ params, items }` | Menu opened |

## Styling

The context menu supports CSS custom properties for theming. Override these on `tbw-grid` or a parent container:

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-context-menu-bg` | `var(--tbw-color-panel-bg)` | Menu background |
| `--tbw-context-menu-fg` | `var(--tbw-color-fg)` | Menu text color |
| `--tbw-context-menu-border` | `var(--tbw-color-border)` | Menu border |
| `--tbw-context-menu-hover` | `var(--tbw-color-row-hover)` | Item hover background |
| `--tbw-menu-min-width` | `10rem` | Minimum menu width |
| `--tbw-menu-item-padding` | `0.375rem 0.75rem` | Menu item padding |
| `--tbw-menu-item-gap` | `0.5rem` | Gap between icon and label |
| `--tbw-font-size-sm` | `0.9285em` | Menu font size |
| `--tbw-font-size-xs` | `0.7857em` | Shortcut text size |
| `--tbw-icon-size` | `1em` | Icon width |

### Example

```css
tbw-grid {
  /* Custom context menu styling */
  --tbw-context-menu-bg: #2d2d2d;
  --tbw-context-menu-fg: #ffffff;
  --tbw-context-menu-border: #444444;
  --tbw-context-menu-hover: #3d3d3d;
  --tbw-menu-item-padding: 0.5rem 1rem;
}
```

### CSS Classes

The menu uses these class names for advanced customization:

| Class | Element |
| --- | --- |
| `.tbw-context-menu` | Menu container |
| `.tbw-context-menu-item` | Menu item row |
| `.tbw-context-menu-item.disabled` | Disabled item |
| `.tbw-context-menu-item.danger` | Danger/delete action |
| `.tbw-context-menu-icon` | Item icon container |
| `.tbw-context-menu-label` | Item label text |
| `.tbw-context-menu-shortcut` | Keyboard shortcut |
| `.tbw-context-menu-separator` | Divider line |

## Accessibility

When the plugin is loaded, the grid's right-click target advertises the popup
trigger to assistive technologies following the
[WAI-ARIA Menu Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/):

- `aria-haspopup="menu"` is set on the grid root once the plugin is attached.
- `aria-expanded` is toggled between `"false"` and `"true"` to reflect the
  menu's open state — including when it closes via <kbd>Esc</kbd>, click
  outside, or a scroll event.
- Menu items inside the popup use `role="menuitem"` and are reachable with
  the arrow keys; <kbd>Enter</kbd> / <kbd>Space</kbd> activates and
  <kbd>Esc</kbd> closes (see [Accessibility guide](/grid/guides/accessibility.md)).

The plugin also respects the keyboard-open path: <kbd>Shift</kbd> +
<kbd>F10</kbd> and the dedicated <kbd>☰ Menu</kbd> key open the menu at the
focused cell with focus moved to the first item.

## See Also

- **[Selection](/grid/plugins/selection.md)** — Row and cell selection
- **[Editing](/grid/plugins/editing.md)** — Inline cell editing
- **[Clipboard](/grid/plugins/clipboard.md)** — Copy/paste cells

---

# Editing Plugin

> Enable inline cell editing with built-in and custom editors.

The Editing plugin enables inline cell editing in the grid. It provides built-in editors for common data types and supports custom editor functions for specialized input scenarios.

## Why Opt-In?

Editing is delivered as a plugin rather than built into the core grid for several reasons:

- **Smaller bundle size** — Applications that only display data don't pay for editing code
- **Clear intent** — Explicit plugin registration makes editing capability obvious in code
- **Runtime validation** — Using `editable: true` without the plugin throws a helpful error

## Installation

```ts
import '@toolbox-web/grid/features/editing';
```

## Basic Usage

Enable the editing feature to use `editable` and `editor` column properties:

#### Angular

```typescript
// Feature import - enables the [editing] input
import { GridEditingDirective, TbwEditor } from '@toolbox-web/grid-angular/features/editing';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  imports: [Grid, TbwEditor, GridEditingDirective],
  template: `
    <tbw-grid
      [rows]="data"
      [columns]="columns"
      [editing]="true"
      (cellCommit)="onCommit($event)" />
  `
})
export class MyGridComponent {
  data = [...];
  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name', editable: true },
    { field: 'price', header: 'Price', type: 'number', editable: true },
  ];

  onCommit(event: CustomEvent) {
    console.log('Edited:', event.detail);
  }
}
```

### Try It

```ts
// EditingBasicEditingDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/editing';

const container = document.getElementById('editing-basic-editing-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

      grid.gridConfig = {
        columns: [
          { field: 'name', header: 'Name', editable: true },
          { field: 'score', header: 'Score', type: 'number', editable: true },
          {
            field: 'role',
            header: 'Role',
            type: 'select',
            editable: true,
            options: [
              { label: 'Admin', value: 'admin' },
              { label: 'User', value: 'user' },
              { label: 'Guest', value: 'guest' },
            ],
          },
        ],
        features: { editing: 'dblclick' },
      };

      grid.rows = [
        { name: 'Alice', score: 95, role: 'admin' },
        { name: 'Bob', score: 82, role: 'user' },
        { name: 'Carol', score: 91, role: 'guest' },
      ];

      grid.on('cell-commit', ({ field, newValue }) => {
        console.log('Edited:', field, '→', newValue);
      });
}
```

Double-click any cell to start editing. Press Enter to commit or Escape to cancel.

## Built-in Editors

The editor used for a cell is chosen from the column's `type`. No editor code is required for the common cases — set `type` and `editable: true`, and the matching native input is rendered:

| Column `type`        | Built-in editor   | Configure via                                                          |
| -------------------- | ----------------- | ---------------------------------------------------------------------- |
| `'string'` (default) | Text `<input>`    | `editorParams`: `maxLength`, `pattern`, `placeholder`                  |
| `'number'`           | Number `<input>`  | `editorParams`: `min`, `max`, `step`, `placeholder`                    |
| `'date'`             | Date `<input>`    | `editorParams`: `min`, `max` (ISO `'YYYY-MM-DD'`), `placeholder`, `default` |
| `'boolean'`          | Checkbox          | _(no params)_                                                          |
| `'select'`           | Dropdown `<select>` | column `options`; `editorParams`: `includeEmpty`, `emptyLabel`       |

`editorParams` is set on the column and tunes the built-in editor's HTML attributes:

```ts
grid.gridConfig = {
  columns: [
    { field: 'name', editable: true, editorParams: { maxLength: 50, placeholder: 'Full name' } },
    { field: 'price', type: 'number', editable: true, editorParams: { min: 0, step: 0.01 } },
    { field: 'hireDate', type: 'date', editable: true, editorParams: { min: '2020-01-01' } },
    {
      field: 'department',
      type: 'select',
      editable: true,
      // `options` is a column property — an array of { label, value } (or a function returning one).
      options: [
        { label: 'Engineering', value: 'eng' },
        { label: 'Sales', value: 'sales' },
      ],
      editorParams: { includeEmpty: true, emptyLabel: '-- Select --' },
    },
  ],
  features: { editing: 'dblclick' },
};
```

For anything beyond these — overlay pickers, multi-field composites, or framework components — provide a custom `editor` on the column (see [Custom Editors](#custom-editors) below) or, in a framework adapter, the adapter's editor base class. The select editor's choices come from the column-level `options` property (not `editorParams`); `editorParams.includeEmpty`/`emptyLabel` only control the leading blank entry.

## Add/Remove Rows

```ts
// EditingAddRemoveRowsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/editing';

const container = document.getElementById('editing-add-remove-rows-demo');
if (container) {
  // Toolbar with Add Row button
      const toolbar = container.querySelector('[data-controls-id="editing-add-remove-rows-demo"]');
      toolbar.style.cssText = 'padding: 8px; border-bottom: 1px solid #e5e7eb; display: flex; gap: 8px;';

      const addBtn = document.createElement('button');
      addBtn.textContent = '+ Add Row';
      addBtn.style.cssText = `
        padding: 6px 12px;
        background: #3b82f6;
        color: white;
        border: none;
        border-radius: 4px;
        cursor: pointer;
        font-size: 14px;
      `;
      toolbar.appendChild(addBtn);

      // Grid
      const grid = queryGrid('tbw-grid', container);
      grid.style.cssText = 'flex: 1;';

      let idCounter = 4;

      grid.gridConfig = {
        columns: [
          { field: 'id', header: 'ID' },
          { field: 'name', header: 'Name', editable: true },
          { field: 'email', header: 'Email', editable: true },
          {
            field: 'actions',
            header: 'Actions',
            renderer: (ctx) => {
              const btn = document.createElement('button');
              btn.textContent = 'Delete';
              btn.style.cssText = `
                padding: 4px 8px;
                background: #ef4444;
                color: white;
                border: none;
                border-radius: 4px;
                cursor: pointer;
                font-size: 12px;
              `;
              btn.onclick = () => {
                const idx = grid.rows.findIndex((r) => r.id !== undefined && r.id === ctx.row.id);
                if (idx >= 0) grid.removeRow(idx);
              };
              return btn;
            },
          },
        ],
        features: { editing: 'dblclick' },
      };

      grid.rows = [
        { id: 1, name: 'Alice', email: 'alice@example.com' },
        { id: 2, name: 'Bob', email: 'bob@example.com' },
        { id: 3, name: 'Carol', email: 'carol@example.com' },
      ];

      addBtn.addEventListener('click', () => {
        grid.insertRow(grid.rows.length, { id: idCounter++, name: '', email: '' });
      });
}
```

To dynamically add or remove rows from the grid, simply assign a new array to the `rows` property. The grid reactively updates to display the new data. Use a custom `renderer` in an "Actions" column to provide a delete button for each row.

## Programmatic Row Updates

To update individual row values without reassigning the entire `rows` array, use the **Row Update API**:

```typescript
// Update a single row by ID
grid.updateRow('emp-123', { status: 'active', salary: 75000 });

// Batch update multiple rows
grid.updateRows([
  { id: 'emp-123', changes: { status: 'active' } },
  { id: 'emp-456', changes: { department: 'Engineering' } },
]);

// Listen for programmatic updates
grid.on('cell-change', ({ rowId, changes }) => {
  console.log('Row updated:', rowId, changes);
});
```

:::note
The `cell-change` event fires for programmatic updates via `updateRow()`/`updateRows()`. The `cell-commit` event fires for inline edits made by users.
:::

See the [API Reference](/grid/api-reference.md#row-update-api) for full documentation.

## Conditional Editing

By default, `editable: true` makes a column editable for **every** row. For more fine-grained control, use a **function** to decide per-row whether a cell can be edited.

### Try It

```ts
// EditingConditionalDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/editing';

const container = document.getElementById('editing-conditional-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    // Row-level gate: archived rows cannot be edited at all
    rowEditable: (row) => !row.archived,
    columns: [
      { field: 'name', header: 'Name', editable: true },
      { field: 'price', header: 'Price', type: 'number', editable: (row) => row.status === 'draft' },
      {
        field: 'status',
        header: 'Status',
        type: 'select',
        editable: true,
        options: [
          { label: 'Draft', value: 'draft' },
          { label: 'Published', value: 'published' },
        ],
      },
      {
        field: 'archived',
        header: 'Archived',
        type: 'boolean',
        renderer: (ctx) => {
          const span = document.createElement('span');
          span.textContent = ctx.value ? '🔒 Yes' : 'No';
          return span;
        },
      },
    ],
    features: { editing: 'dblclick' },
  };

  grid.rows = [
    { name: 'Widget', price: 9.99, status: 'draft', archived: false },
    { name: 'Gadget', price: 19.99, status: 'published', archived: false },
    { name: 'Doohickey', price: 4.99, status: 'draft', archived: false },
    { name: 'Thingamajig', price: 29.99, status: 'published', archived: true },
  ];
}
```

In this demo, **Price** is only editable on "draft" rows, and the archived row (Thingamajig) is locked entirely via `rowEditable`.

#### Angular

```typescript
columns: ColumnConfig[] = [
  { field: 'name', editable: true },
  { field: 'price', editable: (row: any) => row.status === 'draft' },
];
```

### Row-Level Editability (`rowEditable`)

To block editing for an **entire row** regardless of column config, set `rowEditable` on `gridConfig`. This acts as a gate before any column-level `editable` check:

```ts
grid.gridConfig = {
  rowEditable: (row) => !row.archived,
  columns: [
    { field: 'name', editable: true },
    { field: 'price', editable: (row) => row.status === 'draft' },
  ],
  features: { editing: 'dblclick' },
};
```

**Resolution order** — a cell is editable when **both** pass:
1. `gridConfig.rowEditable(row)` returns `true` (or is omitted)
2. Column `editable` is `true` or `editable(row)` returns `true`

:::tip
Keep `editable` and `rowEditable` callbacks fast — they are called on every editability check (click, keyboard, grid-mode render, tab navigation).
:::

## Edit Triggers

Configure how editing is triggered with the `editOn` option:

```ts
features: { editing: 'dblclick' } // or 'click', 'manual'
```

| Value       | Behavior                                      |
| ----------- | --------------------------------------------- |
| `'click'`   | Single click on cell enters edit mode         |
| `'dblclick'`| Double-click on cell enters edit mode (default) |
| `'manual'`  | Programmatic only via `beginCellEdit(rowIndex, field)` |

```ts
// EditingClickToEditDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/editing';

const container = document.getElementById('editing-click-to-edit-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name', editable: true },
      { field: 'email', header: 'Email', editable: true },
      { field: 'role', header: 'Role', editable: true },
    ],
    features: { editing: 'click' },
  };

  grid.rows = [
    { name: 'Alice', email: 'alice@example.com', role: 'Developer' },
    { name: 'Bob', email: 'bob@example.com', role: 'Designer' },
    { name: 'Carol', email: 'carol@example.com', role: 'Manager' },
    { name: 'Dan', email: 'dan@example.com', role: 'Analyst' },
  ];
}
```

The demo above uses `editOn: 'click'` — a single click enters edit mode.

### Keyboard Shortcuts (Row Mode)

| Key | Behavior |
| --- | -------- |
| **Enter** | Start editing the entire row (all editable cells get editors) |
| **F2** | Start editing only the focused cell (single-cell edit) |
| **Escape** | Cancel the current edit and revert changes |
| **Tab** / **Shift+Tab** | Move to next/previous editable cell |
| **Arrow Up/Down** | Handled by the focused editor (e.g. number stepper, select options, textarea caret). Press **Enter**, **Escape**, or **Tab** to leave edit mode before arrow keys resume cell navigation. |
| **Space** | Toggle boolean cells (when not in edit mode) |

:::tip
Use **F2** when you only need to edit one cell without activating editors on the entire row.
:::

## Grid Mode (Spreadsheet-like Editing)

For data entry forms or spreadsheet-like interfaces, use `mode: 'grid'` to make all editable cells show their editors at all times:

```ts
features: { editing: { mode: 'grid' } }
```

| Mode    | Behavior                                                    |
| ------- | ----------------------------------------------------------- |
| `'row'` | Default. Click/dblclick to enter edit mode, Escape to exit |
| `'grid'`| All editors visible immediately. Excel-like navigation.     |

In **grid mode**:
- All `editable: true` cells render with their editors on load
- Tab/Shift+Tab navigates between editable cells (wraps to next/prev row)
- `cell-commit` events fire normally when values change

### Excel-like Navigation vs Edit Mode

```ts
// EditingGridModeDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/editing';

const container = document.getElementById('editing-grid-mode-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID' },
      { field: 'product', header: 'Product', editable: true },
      { field: 'quantity', header: 'Qty', type: 'number', editable: true },
      { field: 'price', header: 'Price', type: 'number', editable: true },
    ],
    features: { editing: { mode: 'grid' } },
  };

  grid.rows = [
    { id: 1, product: 'Widget A', quantity: 10, price: 9.99 },
    { id: 2, product: 'Widget B', quantity: 5, price: 14.99 },
    { id: 3, product: 'Gadget X', quantity: 3, price: 29.99 },
    { id: 4, product: 'Gadget Y', quantity: 8, price: 19.99 },
  ];

  grid.on('cell-commit', ({ field, value }) => {
    const log = container.querySelector('.event-log');
    if (log) {
      const entry = document.createElement('div');
      entry.textContent = `${field} = ${JSON.stringify(value)}`;
      log.insertBefore(entry, log.firstChild);
      while (log.children.length > 5) {
        log.removeChild(log.lastChild!);
      }
    }
  });
}
```

Grid mode supports Excel-style keyboard interaction with two modes:

| State | How to Enter | Behavior |
| ----- | ------------ | -------- |
| **Navigation** | Press Escape | Arrow keys move between cells. Input is blurred. |
| **Edit** | Press Enter, click input, or start typing | Arrow keys work within the input (cursor position, up/down for numbers). |

- **Escape**: Blurs the current input, switching to navigation mode where arrow keys move the cell focus
- **Enter**: Focuses the current cell's input, switching to edit mode
- **Click**: Clicking directly on an input naturally focuses it (edit mode)
- **Arrow Keys**: In navigation mode, use arrow keys to move between cells. In edit mode, arrows work within the input (e.g., moving cursor in text, incrementing numbers)

This mimics Excel/Google Sheets behavior where you can quickly navigate a grid with arrows, then press Enter to edit a cell.

## Built-in Editors

```ts
// EditingAllColumnTypesDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/editing';

const container = document.getElementById('editing-all-column-types-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

      grid.gridConfig = {
        columns: [
          { field: 'name', header: 'Name (string)', editable: true },
          { field: 'age', header: 'Age (number)', type: 'number', editable: true },
          { field: 'active', header: 'Active (boolean)', type: 'boolean', editable: true },
          { field: 'joined', header: 'Joined (date)', type: 'date', editable: true },
          {
            field: 'role',
            header: 'Role (select)',
            type: 'select',
            editable: true,
            options: [
              { label: 'Admin', value: 'admin' },
              { label: 'User', value: 'user' },
            ],
          },
        ],
        features: { editing: 'dblclick' },
      };

      grid.rows = [
        { name: 'Alice', age: 28, active: true, joined: new Date('2023-01-15'), role: 'admin' },
        { name: 'Bob', age: 34, active: false, joined: new Date('2023-06-20'), role: 'user' },
        { name: 'Carol', age: 25, active: true, joined: new Date('2024-02-10'), role: 'user' },
      ];
}
```

The grid provides appropriate editors based on column `type`:

| Column Type | Editor                              |
| ----------- | ----------------------------------- |
| `string`    | Text input                          |
| `number`    | Number input with validation        |
| `boolean`   | Checkbox                            |
| `date`      | Date picker input                   |
| `select`    | Dropdown (requires `options` array) |

## Editor Parameters

Configure built-in editors using the `editorParams` property. This allows you to set constraints and attributes without creating a custom editor.

```ts
// EditorParametersDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/editing';

  const grid = queryGrid('#demo-editor-parameters');
  if (grid) {
    grid.gridConfig = {
      columns: [
        {
          field: 'price',
          header: 'Price',
          type: 'number',
          editable: true,
          editorParams: { min: 0, max: 1000, step: 0.01, placeholder: '0.00' },
        },
        {
          field: 'code',
          header: 'Product Code',
          editable: true,
          editorParams: { maxLength: 10, pattern: '[A-Z0-9]+', placeholder: 'ABC123' },
        },
        {
          field: 'expiry',
          header: 'Expiry Date',
          type: 'date',
          editable: true,
          editorParams: { min: '2024-01-01', max: '2030-12-31' },
        },
        {
          field: 'status',
          header: 'Status',
          type: 'select',
          editable: true,
          options: [
            { label: 'Active', value: 'active' },
            { label: 'Inactive', value: 'inactive' },
          ],
          editorParams: { includeEmpty: true, emptyLabel: '-- Select --' },
        },
      ],
      features: { editing: 'dblclick' },
    };

    grid.rows = [
      { price: 29.99, code: 'PROD001', expiry: new Date('2025-06-15'), status: 'active' },
      { price: 149.5, code: 'PROD002', expiry: new Date('2026-01-01'), status: 'inactive' },
      { price: null, code: '', expiry: null, status: '' },
    ];
  }
```

### Number Editor

```ts
{
  field: 'price',
  type: 'number',
  editable: true,
  editorParams: {
    min: 0,           // Minimum value
    max: 1000000,     // Maximum value
    step: 0.01,       // Increment for up/down arrows
    placeholder: 'Enter price'
  }
}
```

### Text Editor

```ts
{
  field: 'name',
  editable: true,
  editorParams: {
    maxLength: 100,          // Maximum character length
    pattern: '[A-Za-z\\s]+', // HTML5 validation pattern
    placeholder: 'Enter name'
  }
}
```

### Date Editor

```ts
{
  field: 'startDate',
  type: 'date',
  editable: true,
  editorParams: {
    min: '2024-01-01',      // Minimum date (ISO format)
    max: '2024-12-31',      // Maximum date (ISO format)
    placeholder: 'Select date',
    default: '2024-01-01'   // Fallback when non-nullable column is cleared
  }
}
```

### Select Editor

```ts
{
  field: 'status',
  type: 'select',
  editable: true,
  options: [
    { label: 'Active', value: 'active' },
    { label: 'Inactive', value: 'inactive' }
  ],
  editorParams: {
    includeEmpty: true,          // Add empty option at start
    emptyLabel: '-- Select --'   // Label for empty option
  }
}
```

### TypeScript Types

```ts
import type {
  EditorParams,
  NumberEditorParams,
  TextEditorParams,
  DateEditorParams,
  SelectEditorParams
} from '@toolbox-web/grid/plugins/editing';
```

## Nullable Columns

Use the `nullable` column property to control whether a field can be set to `null`.
Both `true` and `false` actively manage empty-input behaviour; omitting `nullable`
preserves the default behaviour for each editor type.

### nullable: true

Editors allow clearing the field and commit `null`:

```ts
columns: [
  // Text & number: clearing the input commits null
  { field: 'nickname', editable: true, nullable: true },
  { field: 'bonus', type: 'number', editable: true, nullable: true },

  // Select: a "(Blank)" option is prepended that commits null
  {
    field: 'department', type: 'select', editable: true, nullable: true,
    options: [{ label: 'Engineering', value: 'eng' }, { label: 'Sales', value: 'sales' }],
  },

  // Date: clearing the date commits null
  { field: 'endDate', type: 'date', editable: true, nullable: true },
]
```

The select editor's blank-option label defaults to `"(Blank)"` and can be
customised via `editorParams.emptyLabel`.

### nullable: false

Editors prevent null values by providing sensible defaults when the user clears a field:

| Editor   | Behaviour when cleared                                                      |
|----------|-----------------------------------------------------------------------------|
| **Text** | Commits `""` (empty string)                                                 |
| **Number** | Commits `editorParams.min` if set, otherwise `0`                          |
| **Date** | Commits `editorParams.default` if set, otherwise today's date             |
| **Select** | No blank option is shown — the user must pick a value                   |

```ts
columns: [
  { field: 'name', editable: true, nullable: false },
  { field: 'price', type: 'number', editable: true, nullable: false,
    editorParams: { min: 1 } },              // clears to 1
  { field: 'startDate', type: 'date', editable: true, nullable: false,
    editorParams: { default: '2024-01-01' } }, // clears to Jan 1, 2024
]
```

> Custom editors receive `column.nullable` via the `ColumnEditorContext.column`
> reference and can implement their own nullable logic.

## Type-Level Defaults

Instead of configuring renderers and editors on every column, you can define **type-level defaults** that apply to all columns of a given type. This is especially useful for custom types like `country`, `currency`, or `status` that appear across multiple grids.

### Grid-Level Type Defaults

Define type defaults in your grid configuration:

#### Angular

```typescript
// Feature import - enables the [editing] input
import { GridEditingDirective } from '@toolbox-web/grid-angular/features/editing';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig, TypeDefault } from '@toolbox-web/grid';

@Component({
  imports: [Grid, GridEditingDirective],
  template: `<tbw-grid [rows]="data" [columns]="columns" [editing]="true" [typeDefaults]="typeDefaults" />`
})
export class MyGridComponent {
  data = [...];
  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name', editable: true },
    { field: 'country', header: 'Country', type: 'country', editable: true },
  ];

  typeDefaults: Record<string, TypeDefault> = {
    country: {
      renderer: (ctx) => {
        const span = document.createElement('span');
        span.textContent = `🌍 ${ctx.value}`;
        return span;
      },
    },
  };
}
```

### Application-Level Type Defaults

For defaults that apply across **all grids** in your application, use the framework adapter's type registry:

#### Angular

```typescript
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideGridTypeDefaults } from '@toolbox-web/grid-angular';
import { CountryBadgeComponent, CountryEditorComponent } from './components';

export const appConfig: ApplicationConfig = {
  providers: [
    provideGridTypeDefaults({
      country: {
        renderer: CountryBadgeComponent,
        editor: CountryEditorComponent,
      },
      currency: {
        renderer: CurrencyCellComponent,
      },
    }),
  ],
};

// grid.component.ts - type defaults automatically apply
// Feature import - enables the [editing] input
import { GridEditingDirective } from '@toolbox-web/grid-angular/features/editing';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  imports: [Grid, GridEditingDirective],
  template: `<tbw-grid [rows]="data" [columns]="columns" [editing]="true" />`
})
export class GridComponent {
  data = [...];
  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'country', type: 'country', editable: true }, // Uses registered components
    { field: 'salary', type: 'currency' },
  ];
}
```

### Resolution Priority

When resolving a renderer or editor, the grid checks in this order:

1. **Column-level** — `column.renderer` or `column.editor`
2. **Grid-level** — `gridConfig.typeDefaults[column.type]`
3. **App-level** — Framework adapter's type registry
4. **Built-in** — Default editors for `string`, `number`, `boolean`, etc.

A column-level renderer/editor always takes precedence, allowing overrides when needed.

### Editor Parameters Merging

When using type defaults with `editorParams`, parameters are merged with column-level params taking precedence:

```ts
// Grid config
typeDefaults: {
  number: {
    editorParams: { min: 0, step: 1 }, // Type-level defaults
  },
}

// Column config
{ field: 'price', type: 'number', editorParams: { step: 0.01 } }

// Result: { min: 0, step: 0.01 } — column's step overrides type default
```

### Custom Type Names

The `type` property accepts any string, not just built-in types. Use descriptive names for your domain:

```ts
type: 'country'    // Geographic data
type: 'currency'   // Money values
type: 'priority'   // High/Medium/Low
type: 'status'     // Active/Pending/Archived
type: 'rating'     // Star ratings
```

TypeScript provides IntelliSense for built-in types while allowing custom strings:

```ts
import type { ColumnType } from '@toolbox-web/grid';

const type: ColumnType = 'country'; // Works! Custom types allowed
```

## Custom Editors

```ts
// EditingCustomEditorDemo.astro
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/editing';

const container = document.getElementById('editing-custom-editor-demo');
if (container) {
  const grid = await queryGrid('tbw-grid', container, true);

  if (grid) {
      // Register custom styles for the editor
      grid.registerStyles(
        'priority-editor',
        `
        .data-grid-row > .cell.editing:has(.priority-editor) {
          justify-content: start;
        }
        .priority-editor {
          display: flex;
          gap: 4px;
          padding: 2px;
        }
        .priority-editor button {
          --button-background: light-dark(#ffffff, #333333);
          --button-color: light-dark(#333333, #ffffff);
          padding: 2px 8px;
          border: 1px solid #ccc;
          border-radius: 3px;
          background: var(--button-background);
          color: var(--button-color);
          cursor: pointer;
          user-select: none;
        }
        .priority-editor button.selected {
          --button-background: #3b82f6;
          --button-color: #ffffff;
        }
      `,
      );

      grid.gridConfig = {
        columns: [
          { field: 'name', header: 'Name', editable: true },
          {
            field: 'priority',
            header: 'Priority',
            editable: true,
            editor: (ctx) => {
              const editorEl = document.createElement('div');
              editorEl.className = 'priority-editor';

              ['Low', 'Medium', 'High'].forEach((level) => {
                const btn = document.createElement('button');
                btn.textContent = level;
                if (ctx.value === level) btn.classList.add('selected');

                btn.onclick = () => {
                  // Remove selected from siblings, add to clicked
                  editorEl.querySelectorAll('button').forEach((b) => b.classList.remove('selected'));
                  btn.classList.add('selected');
                  ctx.commit(level);
                };
                editorEl.appendChild(btn);
              });

              return editorEl;
            },
          },
        ],
        features: { editing: 'dblclick' },
      };

      grid.rows = [
        { name: 'Task A', priority: 'High' },
        { name: 'Task B', priority: 'Medium' },
        { name: 'Task C', priority: 'Low' },
      ];
  }
}
```

For specialized input needs, provide a custom `editor` function:

```ts
{
  field: 'status',
  header: 'Status',
  editable: true,
  editor: (ctx) => {
    const select = document.createElement('select');
    select.innerHTML = `
      <option value="pending">Pending</option>
      <option value="active">Active</option>
      <option value="completed">Completed</option>
    `;
    select.value = ctx.value;

    // Commit on change
    select.onchange = () => ctx.commit(select.value);

    // Cancel on Escape
    select.onkeydown = (e) => {
      if (e.key === 'Escape') ctx.cancel();
    };

    return select;
  },
}
```

Double-click the Priority column to see button-based editing:

### Editor Context

The `ctx` object passed to custom editors contains:

| Property | Type | Description |
| -------- | ---- | ----------- |
| `value` | `unknown` | Current cell value |
| `row` | `T` | Full row data |
| `column` | `ColumnConfig` | Column configuration |
| `field` | `string` | Field name |
| `rowId` | `string` | Row ID (from `getRowId`) |
| `commit(value)` | `function` | Call to save new value |
| `cancel()` | `function` | Call to discard changes |
| `updateRow(changes)` | `function` | Update other fields on the same row (triggers `cell-change` events) |
| `onValueChange(cb)` | `function` | Register a callback to receive pushed values when the cell's value changes externally (e.g., via `updateRow` from another cell's commit) |

:::tip[Preventing Row Height Growth]
Built-in editors are sized to match the cell exactly, so row height stays constant when entering edit mode. Custom editors inherit this behavior automatically if they return a standard `<input>`, `<select>`, or `<textarea>` element.

If your custom editor uses a non-standard element (e.g., a `<div>` with buttons), ensure it doesn't exceed the cell height. Add these styles to your editor's root element:

```css
max-height: 100%;
overflow: hidden;
```

For editors that need overlays (datepickers, dropdown panels), render the overlay **outside** the cell using `position: fixed` or `position: absolute` on a `<body>`-appended element, and register it with `grid.registerExternalFocusContainer(overlay)` so the grid doesn't close the editor when the overlay receives focus.
:::

### Cascade Updates (onValueChange)

When one cell's commit updates other fields via `updateRow()`, any editors open on those fields
receive the new value automatically. The grid does this for built-in editors out of the box.

For custom editors, use `onValueChange` to keep your inputs in sync:

#### Angular

```typescript
// Angular editors receive onValueChange in the editor context
// BaseGridEditor handles it automatically for ControlValueAccessor editors.
// For manual editors, subscribe in your component:

import { Component, OnInit } from '@angular/core';
import { BaseGridEditor } from '@toolbox-web/grid-angular/features/editing';

@Component({
  template: `<input type="number" [value]="total" (change)="onInput($event)" />`
})
export class TotalEditorComponent extends BaseGridEditor<number> implements OnInit {
  total = 0;

  ngOnInit() {
    this.total = this.context.value ?? 0;

    // Stay in sync when another cell updates this field
    this.context.onValueChange?.((newValue) => {
      this.total = newValue ?? 0;
    });
  }

  onInput(event: Event) {
    const num = Number((event.target as HTMLInputElement).value);
    this.total = num;
    this.context.commit(num);
  }
}
```

This is especially useful when fields are interdependent — for example, updating `quantity`
recalculates `total`:

#### Angular

```typescript
@Component({
  template: `<tbw-grid [rows]="data" [columns]="columns" [editing]="true" (cellCommit)="onCommit($event)" />`
})
export class MyGridComponent {
  onCommit(event: CustomEvent) {
    if (event.detail.field === 'quantity') {
      const price = event.detail.row.price;
      event.detail.updateRow({ total: price * event.detail.value });
    }
  }
}
```

## Keyboard Shortcuts

| Key | Action |
| --- | ------ |
| **Enter** (not editing) | Start editing focused row |
| **Enter** (while editing) | Commit edit and move down |
| **Tab** | Commit and move to next editable cell |
| **Shift+Tab** | Commit and move to previous editable cell |
| **Escape** | Cancel edit, restore original value |

## Events

```ts
// EditingEditingEventsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/editing';

const container = document.getElementById('editing-editing-events-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name', editable: true },
      { field: 'department', header: 'Department', editable: true },
      { field: 'salary', header: 'Salary', type: 'number', editable: true },
    ],
    features: { editing: 'dblclick' },
  };

  grid.rows = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 85000 },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 72000 },
    { id: 3, name: 'Carol White', department: 'Sales', salary: 68000 },
  ];

  const log = container.querySelector('#editing-event-log');
  const clearBtn = container.querySelector('#clear-editing-log');

  function addLog(type: string, detail: string) {
    if (!log) return;
    const msg = document.createElement('div');
    msg.innerHTML = `<span class="event-type">[${type}]</span> ${detail}`;
    log.insertBefore(msg, log.firstChild);
    while (log.children.length > 15) {
      log.lastChild?.remove();
    }
  }

  clearBtn?.addEventListener('click', () => {
    if (log) log.innerHTML = '';
  });

  grid.on('edit-open', (d) => {
    addLog('edit-open', `row ${d.rowIndex} (${d.rowId})`);
  });

  grid.on('edit-close', (d) => {
    addLog('edit-close', `row ${d.rowIndex} (${d.rowId}), reverted: ${d.reverted}`);
  });

  grid.on('cell-commit', (d) => {
    addLog('cell-commit', `field="${d.field}", "${d.oldValue}" → "${d.value}"`);
  });

  grid.on('row-commit', (d) => {
    addLog('row-commit', `row ${d.rowIndex} (${d.rowId}), changed: ${d.changed}`);
  });

  grid.on('changed-rows-reset', (d) => {
    addLog('changed-rows-reset', `${d.rows?.length || 0} rows cleared`);
  });
}
```

The EditingPlugin emits events during the editing lifecycle. Double-click a cell to edit,
then press Enter or click away to see the events:

| Event | Type | Description |
| ----- | ---- | ----------- |
| `edit-open` | `EditOpenDetail` | Fired when a row enters edit mode (row mode only) |
| `before-edit-close` | [`BeforeEditCloseDetail`](/grid/plugins/editing/interfaces/beforeeditclosedetail.md) | Fires synchronously before edit state is cleared on commit (row mode only). Managed editors (e.g. Angular Material overlay, MUI Popover) can flush pending values. Does **not** fire on revert. |
| `edit-close` | [`EditCloseDetail`](/grid/plugins/editing/interfaces/editclosedetail.md) | Fired when a row exits edit mode — commit or cancel (row mode only) |
| `cell-commit` | [`CellCommitDetail`](/grid/plugins/editing/interfaces/cellcommitdetail.md) | Fired when a cell value is committed (cancelable) |
| `row-commit` | [`RowCommitDetail`](/grid/plugins/editing/interfaces/rowcommitdetail.md) | Fired when a row editing session ends (cancelable) |
| `changed-rows-reset` | [`ChangedRowsResetDetail`](/grid/plugins/editing/interfaces/changedrowsresetdetail.md) | Fired when `resetChangedRows()` is called |
| `dirty-change` | [`DirtyChangeDetail`](/grid/plugins/editing/interfaces/dirtychangedetail.md) | Fired when a row's dirty state changes (requires `dirtyTracking: true`) |

## Cell Validation

```ts
// EditingCellValidationDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/editing';

const container = document.getElementById('editing-cell-validation-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

      grid.gridConfig = {
        columns: [
          { field: 'name', header: 'Name', editable: true },
          { field: 'email', header: 'Email', editable: true },
          { field: 'salary', header: 'Salary', type: 'number', editable: true },
        ],
        features: { editing: 'dblclick' },
      };

      grid.rows = [
        { id: 1, name: 'Alice', email: 'alice@example.com', salary: 85000 },
        { id: 2, name: 'Bob', email: 'bob@example.com', salary: 72000 },
        { id: 3, name: 'Carol', email: 'carol@example.com', salary: 68000 },
      ];

      // Mark invalid cells (but don't cancel the edit)
      grid.on('cell-commit', ({ field, value, setInvalid }) => {

        if (field === 'email' && typeof value === 'string' && !value.includes('@')) {
          setInvalid('Email must contain @');
        }

        if (field === 'salary' && typeof value === 'number' && value <= 0) {
          setInvalid('Salary must be positive');
        }
      });

      // Reject row commit if there are invalid cells
      grid.on('row-commit', ({ rowId }, e) => {
        if (editingPlugin.hasInvalidCells(rowId)) {
          e.preventDefault(); // Reverts entire row to original values
          // In real app, show a toast or inline message instead of alert
          console.warn('Row reverted due to validation errors');
        }
      });
}
```

Use `setInvalid()` in the `cell-commit` event to mark cells as invalid without canceling the edit.
Invalid cells are highlighted with a red outline and can be styled with CSS custom properties.

Use `preventDefault()` in the `row-commit` event to reject the entire row if validation fails,
reverting all changes to the original values.

### Validation Methods

The EditingPlugin provides these methods for managing validation state:

| Method | Description |
| ------ | ----------- |
| `setInvalid(rowId, field, message?)` | Mark a cell as invalid |
| `clearInvalid(rowId, field)` | Clear invalid state for a cell |
| `clearRowInvalid(rowId)` | Clear all invalid cells in a row |
| `clearAllInvalid()` | Clear all invalid cells |
| `isCellInvalid(rowId, field)` | Check if a cell is invalid |
| `hasInvalidCells(rowId)` | Check if a row has any invalid cells |
| `getInvalidMessage(rowId, field)` | Get the validation message |

### CSS Custom Properties

Style invalid cells by overriding these CSS variables:

```css
tbw-grid {
  --tbw-invalid-bg: #fef2f2;
  --tbw-invalid-border-color: #ef4444;
}
```

## Configuration Validation

If you use `editable: true` or `editor` without enabling the editing feature, the grid throws a helpful error:

```
[tbw-grid] Configuration error:

Column(s) [name, price] use the "editable" column property, but the required plugin is not loaded.
  → Enable the feature:
    import '@toolbox-web/grid/features/editing';
    features: { editing: true }
```

This runtime validation helps catch misconfigurations early during development.

### Opting out without removing column config

If you want to keep `editor` / `editable` declarations on your columns but
temporarily turn editing off (e.g. for a read-only mode), set
`features.editing` to `false` explicitly. The validator treats this as an
intentional opt-out and will not throw, so you can flip the feature back on
without touching column definitions:

```ts
gridConfig = {
  features: { editing: false }, // explicit off — no validation error
  columns: [{ field: 'name', editor: 'text' }],
};
```

## Focus Management

### Focus Trap

Enable `focusTrap` to prevent accidental focus loss during editing. When focus leaves
the grid during an active edit, it is automatically returned to the editing cell:

```ts
features: {
  editing: {
    editOn: 'dblclick',
    focusTrap: true,
  },
}
```

Elements registered via `grid.registerExternalFocusContainer()` are excluded from the
trap — overlays (datepickers, dropdowns) continue to work normally.

### External Focus Containers

Custom editors that append elements to `<body>` (e.g., datepicker overlays, dropdown
panels) should register with the grid so focus inside them doesn't close the editor:

```ts
// In your editor function — get the grid element from the DOM
editor: (ctx) => {
  const input = document.createElement('input');
  const overlay = document.createElement('div');
  overlay.className = 'my-overlay';
  document.body.appendChild(overlay);

  // Get the grid element to register the overlay
  const grid = input.closest('tbw-grid');
  grid?.registerExternalFocusContainer(overlay);

  // When done, unregister
  const origCancel = ctx.cancel;
  ctx.cancel = () => {
    grid?.unregisterExternalFocusContainer(overlay);
    overlay.remove();
    origCancel();
  };

  return input;
}
```

> **Angular:** `BaseOverlayEditor` handles registration automatically.

## Dirty Tracking

Enable dirty tracking to compare each row's current data against its original (baseline)
snapshot. This lets you detect which rows have been modified, display visual indicators,
and revert changes — useful for "save changes" workflows.

### Configuration

```ts
features: {
  editing: {
    dirtyTracking: true,
  },
}
```

When enabled, the plugin captures a deep-clone baseline of each row when data is first
loaded (or when `grid.rows` is reassigned). Baselines are keyed by row ID, so
`gridConfig.getRowId` (or a row `id`/`_id` property) is required.

### API Methods

Access via `grid.getPluginByName('editing')`:

| Method / Property | Returns | Description |
| --- | --- | --- |
| `isDirty(rowId)` | `boolean` | Whether the row differs from its baseline |
| `isPristine(rowId)` | `boolean` | Opposite of `isDirty` |
| `dirty` | `boolean` | Whether **any** row is dirty |
| `pristine` | `boolean` | Whether **all** rows are pristine |
| `getDirtyRows()` | `DirtyRowEntry[]` | All dirty rows with `{ id, original, current }` |
| `dirtyRowIds` | `string[]` | IDs of all dirty rows |
| `getOriginalRow(rowId)` | `T \| undefined` | Deep clone of the baseline row |
| `markAsPristine(rowId)` | `void` | Re-snapshot baseline from current data (call after save) |
| `markAsDirty(rowId)` | `void` | Force-mark a row dirty (e.g., after external mutation) |
| `markAllPristine()` | `void` | Re-snapshot all baselines (call after batch save) |
| `revertRow(rowId)` | `void` | Revert a row to its baseline values |

### Events

The `dirty-change` event fires whenever a row's dirty state changes:

```ts
grid.on('dirty-change', ({ rowId, row, original, type }) => {
  // type: 'modified' | 'new' | 'reverted' | 'pristine'
  console.log(`Row ${rowId}: ${type}`);
});
```

### Example: Save Workflow

```ts
const editing = grid.getPluginByName('editing');

// Check if there are unsaved changes
if (editing.dirty) {
  const dirtyRows = editing.getDirtyRows();
  await api.saveAll(dirtyRows.map(r => r.current));
  editing.markAllPristine();
}
```

## Imperative Bulk-Edit API

For programmatic row editing (e.g. wiring an "Edit" toolbar button, building a custom save flow, or driving edits from outside the grid), the Editing plugin installs the following methods and getters directly on the grid instance:

```typescript
// Start row editing programmatically (all editable cells in the row enter edit mode)
grid.beginBulkEdit(rowIndex);

// Commit the active row edit (fires `row-commit`, applies pending values)
grid.commitActiveRowEdit();

// Cancel the active row edit (discards pending values)
grid.cancelActiveRowEdit();

// Snapshot of rows whose data has been changed this session
const changes: T[] = grid.changedRows;

// IDs of changed rows — requires `gridConfig.getRowId` (or an `id`/`_id` field)
const ids: string[] = grid.changedRowIds;

// Clear change tracking — pass `silent: true` to suppress events
grid.resetChangedRows();
```

:::tip[changedRows vs Dirty Tracking]
`changedRows` / `changedRowIds` is the lightweight session-level "what did the user commit?" tracker — it grows as each cell-/row-commit lands and is cleared by `resetChangedRows()`.

For richer per-row baseline diffing (original vs current, revert, programmatic mark-dirty), enable [Dirty Tracking](#dirty-tracking) and use the plugin's `getDirtyRows()` / `revertRow()` / `markAsPristine()` API instead.
:::

## Row CSS Classes

When dirty tracking is enabled, the EditingPlugin automatically applies CSS classes
to rows based on their state:

| CSS Class | Applied When |
| --- | --- |
| `tbw-row-dirty` | Row data differs from its baseline |
| `tbw-row-new` | Row was inserted via `insertRow()` |

These classes are toggled after every render, so they stay in sync with the data.

### Styling Dirty Rows

```css
tbw-grid .data-grid-row.tbw-row-dirty {
  background-color: #fffde7; /* Light yellow highlight */
}
tbw-grid .data-grid-row.tbw-row-new {
  background-color: #e8f5e9; /* Light green highlight */
}
```

## Editing Stability

When rows are sorted, filtered, or grouped while a row is being edited, the
EditingPlugin preserves the active edit session. The plugin tracks the editing row
by identity (object reference) and remaps the edit index after the data pipeline
runs, so the editor stays attached to the correct row even when its position changes.

If the editing row is removed from the processed data (e.g., filtered out), the
edit session is automatically canceled to prevent stale state.

## See Also

- **[Undo/Redo](/grid/plugins/undo-redo.md)** — Track edit history with Ctrl+Z/Y
- **[Clipboard](/grid/plugins/clipboard.md)** — Copy/paste with Ctrl+C/V
- **[Selection](/grid/plugins/selection.md)** — Cell and row selection
- **[Common Patterns](/grid/guides/common-patterns.md)** — Full application recipes with editing
- **[Plugins Overview](/grid/plugins.md)** — Plugin compatibility and combinations

---

# Export Plugin

> Export grid data to CSV or other formats.

The Export plugin lets users download grid data as CSV, JSON, or other formats with a single click or API call. Great for reporting, data backup, or letting users work with data in Excel.

## Installation

```ts
import '@toolbox-web/grid/features/export';
```

## Basic Usage

Enable the feature and call `exportCsv()` or `exportJson()` when you're ready to download. You can also combine it with the selection feature to export only selected rows.

#### Angular

```typescript
// Feature import - enables the [exportFeature] input
import { GridExportDirective } from '@toolbox-web/grid-angular/features/export';
import { Component } from '@angular/core';
import { Grid, injectGrid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-data-grid',
  imports: [Grid, GridExportDirective],
  template: `
    <button (click)="handleExport()">Export CSV</button>
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [exportFeature]="{ fileName: 'employees', includeHeaders: true }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class DataGridComponent {
  grid = injectGrid();
  rows = [];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
  ];

  handleExport() {
    const plugin = this.grid.element()?.getPluginByName('export');
    plugin?.exportCsv();
  }
}
```

## Demos

### Default Export

```ts
// ExportDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/export';
import '@toolbox-web/grid/features/selection';

const container = document.getElementById('export-default-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, startDate: '2023-01-15' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, startDate: '2022-06-20' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, startDate: '2021-03-10' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, startDate: '2023-08-05' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'number' },
    { field: 'startDate', header: 'Start Date' },
  ];

  const grid = queryGrid('tbw-grid', container)!;
  function rebuild(includeHeaders = true, onlyVisible = true, onlySelected = false) {
    grid.gridConfig = {
      columns,
      features: { selection: 'range', export: { includeHeaders, onlyVisible, onlySelected, fileName: 'grid-export' } },
    };
    grid.rows = sampleData;
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    const v = e.detail.allValues;
    rebuild(v.includeHeaders as boolean, v.onlyVisible as boolean, v.onlySelected as boolean);
  }) as EventListener);

  container.querySelector('.export-csv')?.addEventListener('click', () => grid.getPluginByName('export')?.exportCsv());
  container.querySelector('.export-excel')?.addEventListener('click', () => grid.getPluginByName('export')?.exportExcel());
  container.querySelector('.export-json')?.addEventListener('click', () => grid.getPluginByName('export')?.exportJson());
}
```

Export all visible data to CSV. Toggle "Selected only" and select some rows to export just those.

## Configuration Options

| Option           | Type      | Default   | Description                                              |
| ---------------- | --------- | --------- | -------------------------------------------------------- |
| `fileName`       | `string`  | `'export'`| Base filename (without extension)                        |
| `includeHeaders` | `boolean` | `true`    | Include column headers in export                         |
| `onlyVisible`    | `boolean` | `true`    | Export only visible columns                              |
| `onlySelected`   | `boolean` | `false`   | Export only selected rows (requires SelectionPlugin)     |

## Programmatic API

The ExportPlugin provides methods for exporting data with fine-grained control over which columns and rows to include. Like the ClipboardPlugin, it accepts `columns` and `rowIndices` parameters so you can export exactly the data you need.

### Basic Export

```ts
const exportPlugin = grid.getPluginByName('export');

// Export all visible data to CSV
exportPlugin.exportCsv();

// Export to Excel XML
exportPlugin.exportExcel();

// Export to JSON
exportPlugin.exportJson();
```

### Export with Column/Row Control (`ExportParams`)

```ts
const exportPlugin = grid.getPluginByName('export');

// Export specific columns
exportPlugin.exportCsv({
  columns: ['name', 'email', 'department'],
  fileName: 'contacts',
  includeHeaders: true,
});

// Export specific rows
exportPlugin.exportCsv({
  rowIndices: [0, 3, 7],
  fileName: 'selected-employees',
});

// Export specific columns from specific rows
exportPlugin.exportExcel({
  columns: ['name', 'salary'],
  rowIndices: [0, 1, 2],
  fileName: 'salary-report',
});
```

### `ExportParams` Reference

| Option           | Type                            | Default       | Description                         |
| ---------------- | ------------------------------- | ------------- | ----------------------------------- |
| `fileName`       | `string`                        | config value  | File name (without extension)       |
| `columns`        | `string[]`                      | -             | Specific column fields to export    |
| `rowIndices`     | `number[]`                      | -             | Specific row indices to export      |
| `includeHeaders` | `boolean`                       | config value  | Include column headers in export    |
| `processCell`    | `(value, field, row) => any`    | -             | Custom cell value processor         |
| `processHeader`  | `(header, field) => string`     | -             | Custom header processor             |
| `processHeaderRow` | `(cell, rowIndex) => HeaderRowCell \| null` | -  | Custom processor for plugin-contributed header rows (e.g. column groups). Return `null` to blank a cell; if every cell in a row is blank the row is dropped. **Since 2.10.0** |
| `mode`           | `'raw' \| 'formatted'`          | `'raw'`       | `'raw'` = underlying typed values; `'formatted'` = what the grid displays (`column.format` + type defaults applied) |
| `fileExtension`  | `string`                        | `'.xls'`      | Override file extension for Excel export (e.g. `'.xml'`) |
| `excelStyles`    | `ExcelStyleConfig`              | -             | Excel style configuration (Excel only) |

## Column Groups in Exports

**Since 2.10.0.** When the [`GroupingColumnsPlugin`](/grid/plugins/grouping-columns.md) is installed alongside the export plugin, column group headers are automatically included above the leaf headers.

How it works: the export plugin broadcasts the generic `collectHeaderRows` plugin query before emitting headers. Any plugin can reply with a `HeaderRowContribution` describing extra rows that sit above the leaf header. The grouping plugin replies with one row whose cells carry the group label and a `span` matching the number of leaf columns the group covers. The mechanism is plugin-agnostic — third-party plugins can contribute their own header rows the same way.

| Format | Behaviour |
| ------ | --------- |
| **Excel** | Each contributed row becomes a `<Row>` above the leaf headers. Cells with `span > 1` use `ss:MergeAcross="span-1"` so they appear merged in Excel. Use the new `excelStyles.groupHeaderStyle` to style group rows independently (falls back to `headerStyle`). |
| **JSON** | When at least one plugin contributes a row, output becomes `{ headerRows: HeaderRowContribution[], rows: [...] }`. Without contributions the output stays a flat array — **backward-compatible** for existing consumers. |
| **CSV** | Stays flat. CSV has no native span representation; multi-row headers would confuse most CSV consumers. |

Set `includeHeaders: false` to skip **all** headers (leaf and contributed). It's all-or-nothing — use `processHeaderRow` if you want fine-grained control over which contributed cells to emit.

```ts
// Drop all "Personal" group labels but keep "Work":
grid.getPluginByName('export').exportExcel({
  processHeaderRow: (cell) => (cell.label === 'Personal' ? null : cell),
});

// Style group rows independently of leaf headers:
grid.getPluginByName('export').exportExcel({
  excelStyles: {
    headerStyle: { font: { bold: true } },
    groupHeaderStyle: { font: { bold: true, size: 14 }, fill: { color: '#DDEEFF' } },
  },
});
```

## Custom Output / `.xlsx` Hand-off

The plugin exposes data accessors so you can drive the export pipeline without producing a download — useful for piping rows into a real OOXML writer (e.g. [ExcelJS](https://github.com/exceljs/exceljs)), copying CSV to the clipboard, sending data to a server, or pre-processing before download.

| Method                                | Returns                       | Purpose                                                          |
| ------------------------------------- | ----------------------------- | ---------------------------------------------------------------- |
| `export(params?)`                     | `Record<string, unknown>[]`   | Resolve the rows that would be exported, keyed by `column.field` |
| `formatCsv(data, params?, options?)`  | `string`                      | Format already-resolved rows as CSV (no download)                |
| `formatExcel(data, params?)`          | `string`                      | Format already-resolved rows as Excel XML (no download)          |
| `getResolvedColumns(params?)`         | `ColumnConfig[]`              | The columns (in order) an export would include                   |

All accessors honour `onlyVisible`, `onlySelected`, `columns`, and `rowIndices` (which columns/rows are included), and `processCell` (per-cell transformation — applied once on the values that get written).

`export()` additionally honours `mode` because it owns value resolution. `formatCsv()` / `formatExcel()` are pure formatters: they write whatever you pass in (after running `processCell`) and do **not** apply `mode` — use `export({ mode: 'formatted' })` upstream if you need displayed values.

```ts
import { queryGrid } from '@toolbox-web/grid';
import type { ExportPlugin } from '@toolbox-web/grid/plugins/export';

const grid = queryGrid('tbw-grid');
const exporter = grid.getPluginByName('export') as ExportPlugin;

// 1. "Export what I see" — column.format applied
exporter.exportCsv({ mode: 'formatted' });

// 2. Get the rows without producing a file
const rows = exporter.export();

// 3. Compose: copy CSV to the clipboard
const csv = exporter.formatCsv(exporter.export());
await navigator.clipboard.writeText(csv);

// 4. Hand off raw rows to a real .xlsx writer
import ExcelJS from 'exceljs';
const cols = exporter.getResolvedColumns();
const workbook = new ExcelJS.Workbook();
const sheet = workbook.addWorksheet('Sheet1');
sheet.columns = cols.map((c) => ({ header: c.header ?? c.field, key: c.field }));
sheet.addRows(exporter.export());
const buffer = await workbook.xlsx.writeBuffer();
```

### `mode: 'raw' | 'formatted'`

- `'raw'` (**default**) — values straight from the row (`Date` stays `Date`, numbers stay numbers). Identical to the pre-existing `exportCsv` / `exportExcel` / `exportJson` output, so opting into the new methods is non-breaking.
- `'formatted'` — applies the column-type default formatter and `column.format(value, row)`, returning the same string the user sees in the cell. `processCell` runs last on the formatted value.

## Styled Excel Export

The export plugin produces **XML Spreadsheet 2003** output — a single-XML format natively understood by Excel, without any external dependencies.

:::note[About the file extension]
The correct extension for XML Spreadsheet 2003 is `.xml`, but most operating systems open `.xml` files in a **web browser** instead of Excel. For this reason the export defaults to `.xls`, which ensures the file opens directly in Excel.

The trade-off is that Excel shows a warning when opening the file:

> *"The file format and extension of 'filename.xls' don't match. The file could be corrupted or unsafe. Unless you trust its source, don't open it. Do you want to open it anyway?"*

Clicking **Yes** opens the file normally — the data is not corrupt.

If your users are comfortable opening `.xml` files in Excel (e.g. via right-click → "Open with"), you can set `fileExtension: '.xml'` to avoid the warning entirely:

```ts
exportPlugin.exportExcel({ fileExtension: '.xml' });
```
:::

Pass an `excelStyles` object in `ExportParams` to control header styles, per-column formatting, dynamic cell styling, column widths, and more.

```ts
// ExportStyledExcelDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/export';

const container = document.getElementById('export-styled-excel-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, status: 'Active', startDate: '2023-01-15' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, status: 'Inactive', startDate: '2022-06-20' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, status: 'Active', startDate: '2021-03-10' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, status: 'Active', startDate: '2023-08-05' },
    { id: 5, name: 'Eve Martinez', department: 'Marketing', salary: 70000, status: 'Inactive', startDate: '2024-02-01' },
  ];

  const columns = [
    { field: 'id', header: 'ID', type: 'number' as const },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'number' as const },
    { field: 'status', header: 'Status' },
    { field: 'startDate', header: 'Start Date' },
  ];

  const grid = queryGrid('tbw-grid', container)!;
  grid.gridConfig = {
    columns,
    features: { export: { fileName: 'styled-export' } },
  };
  grid.rows = sampleData;

  // Plain export — no styles
  container.querySelector('.export-unstyled')?.addEventListener('click', () => {
    grid.getPluginByName('export')?.exportExcel({ fileName: 'plain-export' });
  });

  // Styled export — header, column, and conditional cell styles
  container.querySelector('.export-styled')?.addEventListener('click', () => {
    grid.getPluginByName('export')?.exportExcel({
      fileName: 'styled-report',
      excelStyles: {
        headerStyle: {
          font: { bold: true, size: 11, color: '#FFFFFF' },
          fill: { color: '#4472C4' },
          alignment: { horizontal: 'Center' },
          borders: {
            bottom: { style: 'Medium', color: '#2F5496' },
          },
        },
        defaultStyle: {
          font: { name: 'Calibri', size: 10 },
        },
        columnStyles: {
          salary: { numberFormat: '$#,##0', alignment: { horizontal: 'Right' } },
          startDate: { numberFormat: 'yyyy-mm-dd' },
        },
        cellStyle: (value, field) => {
          if (field === 'status') {
            if (value === 'Active') return { fill: { color: '#C6EFCE' }, font: { color: '#006100' } };
            if (value === 'Inactive') return { fill: { color: '#FFC7CE' }, font: { color: '#9C0006' } };
          }
          return undefined;
        },
        autoFitColumns: true,
      },
    });
  });
}
```

Click **Export Styled Excel** to download a formatted `.xls` file with bold headers, currency-formatted salaries, and color-coded status cells. Compare with **Export Plain Excel** to see the difference.

### Header & Default Styles

```ts
exportPlugin.exportExcel({
  fileName: 'report',
  excelStyles: {
    headerStyle: {
      font: { bold: true, size: 12, color: '#FFFFFF' },
      fill: { color: '#4472C4' },
      alignment: { horizontal: 'Center' },
    },
    defaultStyle: {
      font: { name: 'Calibri', size: 10 },
    },
  },
});
```

### Per-Column Styles (Financial Report)

```ts
exportPlugin.exportExcel({
  fileName: 'financial-report',
  excelStyles: {
    headerStyle: { font: { bold: true }, fill: { color: '#D9E2F3' } },
    columnStyles: {
      revenue: { numberFormat: '$#,##0.00', alignment: { horizontal: 'Right' } },
      margin: { numberFormat: '0.0%' },
      date: { numberFormat: 'yyyy-mm-dd' },
    },
    columnWidths: { name: 25, revenue: 15, margin: 10, date: 12 },
  },
});
```

### Dynamic Cell Styling (Conditional Colors)

```ts
exportPlugin.exportExcel({
  fileName: 'status-report',
  excelStyles: {
    cellStyle: (value, field) => {
      if (field === 'status') {
        if (value === 'Active') return { fill: { color: '#C6EFCE' }, font: { color: '#006100' } };
        if (value === 'Inactive') return { fill: { color: '#FFC7CE' }, font: { color: '#9C0006' } };
      }
      return undefined; // fall through to column/default style
    },
  },
});
```

### Auto-Fit Column Widths

```ts
exportPlugin.exportExcel({
  excelStyles: { autoFitColumns: true },
});
```

### `ExcelStyleConfig` Reference

| Option           | Type                                               | Default | Description                                     |
| ---------------- | -------------------------------------------------- | ------- | ----------------------------------------------- |
| `headerStyle`    | `ExcelCellStyle`                                   | -       | Style applied to all header cells               |
| `defaultStyle`   | `ExcelCellStyle`                                   | -       | Default style for all data cells                |
| `columnStyles`   | `Record<string, ExcelCellStyle>`                   | -       | Per-column style overrides (keyed by field)     |
| `cellStyle`      | `(value, field, row) => ExcelCellStyle \| undefined` | -     | Callback for per-cell dynamic styling           |
| `columnWidths`   | `Record<string, number>`                           | -       | Column widths in characters (keyed by field)    |
| `autoFitColumns` | `boolean`                                          | `false` | Auto-fit column widths from content             |

### `ExcelCellStyle` Properties

| Property       | Type     | Description                                               |
| -------------- | -------- | --------------------------------------------------------- |
| `font`         | `object` | `{ name?, size?, bold?, italic?, color? }`                |
| `fill`         | `object` | `{ color, pattern? }` — pattern defaults to `'Solid'`    |
| `numberFormat` | `string` | Excel format code (e.g. `'#,##0.00'`, `'0%'`, `'yyyy-mm-dd'`) |
| `alignment`    | `object` | `{ horizontal?, vertical?, wrapText? }`                   |
| `borders`      | `object` | `{ top?, bottom?, left?, right? }` — each `{ style, color? }` |

## Events

| Event              | Detail                                            | Description                   |
| ------------------ | ------------------------------------------------- | ----------------------------- |
| `export-complete`  | `{ format, fileName, rowCount, columnCount }`     | Fired after an export completes |

## Server-Side Considerations

The ExportPlugin exports the rows currently held in memory (`grid.rows`). It has **no async or server-side support** — it cannot fetch data it hasn't already loaded.

:::caution[Partial data with ServerSidePlugin]
When combined with the [ServerSidePlugin](/grid/plugins/server-side.md), only **cached blocks** are available for export. Rows the user hasn't scrolled to yet are placeholder objects and will not be included. If you need to export the full server dataset, fetch all rows from your API and pass them to the export method directly:

```ts
const allRows = await fetch('/api/data?all=true').then(r => r.json());
grid.rows = allRows;
grid.getPluginByName('export').exportCsv();
```
:::

## See Also

- **[Clipboard](/grid/plugins/clipboard.md)** — Copy cells to clipboard
- **[Print](/grid/plugins/print.md)** — Print the grid
- **[Server-Side Data](../server-side/)** — Block-based virtual scrolling for large datasets

---

# Filtering Plugin

> Add column-level filtering with built-in filter panel and custom filters.

The Filtering plugin adds column header filters with text search, dropdown options, and custom filter panels. It supports both local filtering for small datasets and async handlers for server-side filtering on large datasets.

## Installation

```ts
import '@toolbox-web/grid/features/filtering';
```

## Basic Usage

#### Angular

```typescript
// Feature import - enables the [filtering] input
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridFilteringDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [filtering]="{ debounceMs: 300 }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [...];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name', filterable: true },
    { field: 'status', header: 'Status', filterable: true },
    { field: 'email', header: 'Email', filterable: true },
  ];
}
```

## Demos

### Default Filtering

```ts
// FilteringDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/filtering';

const container = document.getElementById('filtering-default-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, status: 'Active' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, status: 'Active' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, status: 'On Leave' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, status: 'Active' },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000, status: 'Inactive' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000, status: 'Active' },
    { id: 7, name: 'Grace Lee', department: 'Sales', salary: 82000, status: 'Active' },
    { id: 8, name: 'Henry Wilson', department: 'HR', salary: 68000, status: 'Active' },
    { id: 9, name: 'Ivy Chen', department: 'Engineering', salary: 112000, status: 'Active' },
    { id: 10, name: 'Jack Taylor', department: 'Marketing', salary: 78000, status: 'On Leave' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number', filterable: false },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'number' },
    { field: 'status', header: 'Status' },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(debounceMs = 150, caseSensitive = false) {
    grid.gridConfig = {
      columns,
      features: { filtering: { debounceMs, caseSensitive } },
    };
    grid.rows = sampleData;
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    const v = e.detail.allValues;
    rebuild(v.debounceMs as number, v.caseSensitive as boolean);
  }) as EventListener);
}
```

Type in column header filter inputs to filter rows. The plugin debounces input to avoid excessive re-filtering while typing.

### Custom Filter Panel

```ts
// FilteringCustomFilterPanelDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/filtering';

const container = document.getElementById('filtering-custom-filter-panel-demo');
if (container) {
  // Sample data for filtering demos
  const sampleData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, status: 'Active' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, status: 'Active' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, status: 'On Leave' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, status: 'Active' },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000, status: 'Inactive' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000, status: 'Active' },
    { id: 7, name: 'Grace Lee', department: 'Sales', salary: 82000, status: 'Active' },
    { id: 8, name: 'Henry Wilson', department: 'HR', salary: 68000, status: 'Active' },
    { id: 9, name: 'Ivy Chen', department: 'Engineering', salary: 112000, status: 'Active' },
    { id: 10, name: 'Jack Taylor', department: 'Marketing', salary: 78000, status: 'On Leave' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number', filterable: false },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'number' },
    { field: 'status', header: 'Status' },
  ];

  const grid = queryGrid('tbw-grid', container);

      // Custom filter panel for Status column (radio-button style)
      const statusFilterPanel = (container, params) => {
        container.innerHTML = `
          <div style="padding: 8px; min-width: 140px;">
            <div style="font-weight: 600; margin-bottom: 8px; color: var(--tbw-color-fg);">
              Filter by Status
            </div>
            <div class="status-options"></div>
            <button class="clear-btn" style="margin-top: 8px; width: 100%; padding: 6px; cursor: pointer;">
              Clear
            </button>
          </div>
        `;

        const optionsDiv = container.querySelector('.status-options');
        if (!optionsDiv) return;

        const options = ['All', ...params.uniqueValues.map((v) => String(v))];

        options.forEach((opt) => {
          const label = document.createElement('label');
          label.style.cssText = 'display: flex; align-items: center; gap: 6px; padding: 4px 0; cursor: pointer;';
          const isAll = opt === 'All';
          label.innerHTML = `<input type="radio" name="status" value="${opt}" ${
            isAll && params.excludedValues.size === 0 ? 'checked' : ''
          }> ${opt}`;
          const input = label.querySelector('input');
          if (input) {
            input.addEventListener('change', () => {
              if (isAll) {
                params.clearFilter();
              } else {
                // Exclude all except selected
                const excluded = params.uniqueValues.filter((v) => String(v) !== opt);
                params.applySetFilter(excluded);
              }
            });
          }
          optionsDiv.appendChild(label);
        });

        const clearBtn = container.querySelector('.clear-btn');
        if (clearBtn) {
          clearBtn.addEventListener('click', () => params.clearFilter());
        }
      };

      grid.gridConfig = {
        columns,
        features: {
          filtering: {
            debounceMs: 150,
            caseSensitive: false,
            filterPanelRenderer: (container, params) => {
              if (params.field === 'status') {
                statusFilterPanel(container, params);
              } else {
                return undefined; // Use default panel
              }
            },
          },
        },
      };
      grid.rows = sampleData;
}
```

The `filterPanelRenderer` option lets you replace the default filter panel with custom UI.
When the renderer returns `undefined`, the default panel is used for that column.

#### FilterPanelParams

Your custom renderer receives a `params` object with:

**Properties**

| Property         | Type           | Description                            |
| ---------------- | -------------- | -------------------------------------- |
| `field`          | `string`       | The field being filtered               |
| `column`         | `ColumnConfig` | Column configuration                   |
| `uniqueValues`   | `unknown[]`    | All unique values for this field       |
| `excludedValues` | `Set<unknown>` | Currently excluded values (set filter) |
| `searchText`     | `string`       | Current search text                    |
| `currentFilter`  | `FilterModel?` | Active filter model for this field (if any) — use to pre-populate custom UI |

**Methods**

| Method            | Signature                                                                           | Description                               |
| ----------------- | ----------------------------------------------------------------------------------- | ----------------------------------------- |
| `applySetFilter`  | `(excluded: unknown[], valueTo?: unknown) => void`                                  | Apply a set filter; optional `valueTo` stores metadata alongside the filter |
| `applyTextFilter` | `(op: FilterOperator, val: string \| number, valueTo?: string \| number) => void` | Apply a text/number/date filter with operator |
| `clearFilter`     | `() => void`                                                                        | Clear the filter for this field           |
| `closePanel`      | `() => void`                                                                        | Close the filter panel                    |

#### Example: Radio-button Filter

#### Angular

```typescript
// Angular uses a component class extending BaseFilterPanel
import { Component, ViewChild, ElementRef } from '@angular/core';
import { BaseFilterPanel } from '@toolbox-web/grid-angular/features/filtering';

@Component({
  selector: 'app-status-filter',
  template: `
    <div style="padding: 8px;">
      @for (value of ['all'].concat(params().uniqueValues); track value) {
        <label>
          <input
            type="radio"
            name="status"
            [value]="value"
            [checked]="value === 'all' ? !activeValue : value === activeValue"
            (change)="onSelect(value)" />
          {{ value === 'all' ? 'All' : value }}
        </label>
      }
    </div>
  `,
})
export class StatusFilterComponent extends BaseFilterPanel {
  get activeValue() {
    return this.params().currentFilter?.value;
  }

  applyFilter(): void { /* Not used — onSelect handles it */ }

  onSelect(value: string) {
    if (value === 'all') {
      this.params().clearFilter();
    } else {
      const excluded = this.params().uniqueValues.filter((v) => v !== value);
      this.params().applySetFilter(excluded);
    }
    this.params().closePanel();
  }
}
```

```typescript
// In your grid component — pass the component class as filterPanelRenderer
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import { Grid } from '@toolbox-web/grid-angular';
import { StatusFilterComponent } from './status-filter.component';

@Component({
  imports: [Grid, GridFilteringDirective],
  template: `<tbw-grid [rows]="data" [columns]="columns" [filtering]="filterConfig" />`
})
export class MyGridComponent {
  data = [...];
  columns = [
    { field: 'name', header: 'Name', filterable: true },
    { field: 'status', header: 'Status', filterable: true },
  ];

  filterConfig = {
    filterPanelRenderer: StatusFilterComponent,
  };
}
```

### Type-Specific Filter Panels

```ts
// FilteringTypeSpecificFiltersDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/filtering';

const container = document.getElementById('filtering-type-specific-filters-demo');
if (container) {
  const typedData = [
    { id: 1, name: 'Alice Johnson', salary: 95000, hireDate: '2020-03-15', rating: 4.5 },
    { id: 2, name: 'Bob Smith', salary: 75000, hireDate: '2019-07-22', rating: 3.8 },
    { id: 3, name: 'Carol Williams', salary: 105000, hireDate: '2018-11-10', rating: 4.9 },
    { id: 4, name: 'Dan Brown', salary: 85000, hireDate: '2021-01-05', rating: 4.2 },
    { id: 5, name: 'Eve Davis', salary: 72000, hireDate: '2022-06-18', rating: 3.5 },
    { id: 6, name: 'Frank Miller', salary: 98000, hireDate: '2017-09-30', rating: 4.7 },
    { id: 7, name: 'Grace Lee', salary: 82000, hireDate: '2020-12-01', rating: 4.0 },
    { id: 8, name: 'Henry Wilson', salary: 68000, hireDate: '2023-02-14', rating: 3.2 },
  ];

  const grid = queryGrid('tbw-grid', container);

      grid.gridConfig = {
        columns: [
          { field: 'id', header: 'ID', type: 'number', filterable: false },
          { field: 'name', header: 'Name' }, // Set filter (default)
          {
            field: 'salary',
            header: 'Salary',
            type: 'number', // Range slider filter
            filterParams: { min: 50000, max: 150000, step: 5000 },
          },
          {
            field: 'hireDate',
            header: 'Hire Date',
            type: 'date', // Date range picker filter
            filterParams: { min: '2015-01-01', max: '2025-12-31' },
          },
          {
            field: 'rating',
            header: 'Rating',
            type: 'number', // Range slider with smaller step
            filterParams: { min: 1, max: 5, step: 0.1 },
          },
        ],
        features: { filtering: true },
      };
      grid.rows = typedData;
}
```

The Filtering plugin automatically displays appropriate filter UIs based on column type:

| Column Type | Filter UI | Description |
| --- | --- | --- |
| `number` | **Range Slider** | Dual-thumb slider with min/max inputs. Includes a **"Blank" checkbox** to filter rows with no value. |
| `date` | **Date Range Picker** | From/to date inputs with range selection. Includes a **"Show only blank" checkbox** for empty dates. |
| (other) | **Checkbox Set** | Standard multi-select with search. Rows with `null`/`undefined`/empty values appear as a **(Blank)** entry. |

Configure bounds and step via `filterParams` on the column:

```ts
const columns = [
  {
    field: 'salary',
    header: 'Salary',
    type: 'number',
    filterParams: { min: 50000, max: 150000, step: 5000 },
  },
  {
    field: 'hireDate',
    header: 'Hire Date',
    type: 'date',
    filterParams: { min: '2015-01-01', max: '2025-12-31' },
  },
];
```

If `filterParams` is not provided, the plugin auto-detects min/max from the data.

## Server-Side Filtering

```ts
// FilteringAsyncFilteringDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/filtering';

const container = document.getElementById('filtering-async-filtering-demo');
if (container) {
  // Sample data for filtering demos
  const sampleData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, status: 'Active' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, status: 'Active' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, status: 'On Leave' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, status: 'Active' },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000, status: 'Inactive' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000, status: 'Active' },
    { id: 7, name: 'Grace Lee', department: 'Sales', salary: 82000, status: 'Active' },
    { id: 8, name: 'Henry Wilson', department: 'HR', salary: 68000, status: 'Active' },
    { id: 9, name: 'Ivy Chen', department: 'Engineering', salary: 112000, status: 'Active' },
    { id: 10, name: 'Jack Taylor', department: 'Marketing', salary: 78000, status: 'On Leave' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number', filterable: false },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'number' },
    { field: 'status', header: 'Status' },
  ];

  function generateMockData(count: number) {
    const departments = ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'];
    const statuses = ['Active', 'Inactive', 'On Leave'];
    const data = [];
    for (let i = 0; i < count; i++) {
      data.push({
        id: i + 1,
        name: `Employee ${i + 1}`,
        department: departments[i % departments.length],
        salary: 50000 + Math.floor(Math.random() * 50000),
        status: statuses[i % statuses.length],
      });
    }
    return data;
  }

  const grid = queryGrid('tbw-grid', container);

      const serverData = generateMockData(1000);

      // Simulate server-side unique value extraction
      const getUniqueValues = async (field: string): Promise<unknown[]> => {
        await new Promise((r) => setTimeout(r, 200));
        const values = [...new Set(serverData.map((row) => (row as Record<string, unknown>)[field]))];
        return values.sort();
      };

      // Simulate server-side filtering
      // FilterModel uses { field, operator: 'notIn', value: excludedValues[] }
      const applyServerFilters = async (
        filters: { field: string; operator: string; value: unknown[] }[],
      ): Promise<typeof serverData> => {
        await new Promise((r) => setTimeout(r, 300));

        if (filters.length === 0) return serverData;

        return serverData.filter((row) => {
          return filters.every((filter) => {
            const excludedValues = filter.value;
            if (!excludedValues || excludedValues.length === 0) return true;

            const val = (row as Record<string, unknown>)[filter.field];
            // 'notIn' means exclude these values, so row passes if value is NOT in excluded list
            return !excludedValues.includes(val);
          });
        });
      };

      grid.gridConfig = {
        columns,
        features: {
          filtering: {
            valuesHandler: getUniqueValues,
            filterHandler: applyServerFilters,
          },
        },
      };

      grid.rows = serverData;
}
```

For large or server-side datasets, the default local filtering may not be suitable:

- **Not all unique values are available locally** for the filter panel
- **Filtering should happen on the backend** rather than in the browser

Use `valuesHandler` and `filterHandler` to customize this behavior:

```ts
grid.gridConfig = {
  columns: [...],
  features: {
    filtering: {
      // Fetch unique values for a column from the server
      valuesHandler: async (field, column) => {
        const response = await fetch(`/api/distinct-values?field=${field}`);
        return response.json(); // Returns: ['Engineering', 'Marketing', ...]
      },

      // Apply filters on the server
      // FilterModel: { field, type, operator: 'notIn', value: excludedValues[] }
      filterHandler: async (filters, currentRows) => {
        const response = await fetch('/api/data', {
          method: 'POST',
          body: JSON.stringify({ filters }),
        });
        return response.json();
      },
    },
  },
};
```

**Handler signatures:**

| Handler         | Signature                                                    | Returns                  |
| --------------- | ------------------------------------------------------------ | ------------------------ |
| `valuesHandler` | `(field: string, column: ColumnConfig) => Promise<T[]>`      | Unique values for filter |
| `filterHandler` | `(filters: FilterModel[], rows: T[]) => T[] \| Promise<T[]>` | Filtered rows            |

When `valuesHandler` is provided, the filter panel shows a loading indicator while fetching values.
When `filterHandler` is provided, filter application bypasses the local `processRows` hook.

## Configuration Options

### Grid-Level Toggle

You can disable filtering grid-wide using `gridConfig.filterable`:

```ts
grid.gridConfig = {
  filterable: false, // Disables ALL filtering, even on filterable columns
  features: { filtering: true },
};
```

This is useful for toggling filtering on/off at runtime without removing the plugin.

### Plugin Options

| Option                | Type                  | Default | Description                                                       |
| --------------------- | --------------------- | ------- | ----------------------------------------------------------------- |
| `debounceMs`          | `number`              | `300`   | Debounce delay for filter input                                   |
| `caseSensitive`       | `boolean`             | `false` | Case-sensitive string matching                                    |
| `trackColumnState`    | `boolean`             | `false` | Include filter state in column state persistence                  |
| `filterPanelRenderer` | `FilterPanelRenderer` | -       | Custom filter panel renderer                                      |
| `valuesHandler`       | `FilterValuesHandler` | -       | Async handler to fetch unique filter values                       |
| `filterHandler`       | `FilterHandler<TRow>` | -       | Async handler to apply filters remotely                           |

## Column Configuration

```ts
const columns = [
  {
    field: 'name',
    filterable: true, // Enable filtering
    filterType: 'text', // 'text' | 'select' | 'number' | 'date'
  },
  {
    field: 'status',
    filterable: true,
    filterType: 'select',
    filterOptions: ['Active', 'Inactive', 'Pending'],
  },
];
```

## Programmatic API

```ts
const plugin = grid.getPluginByName('filtering');

// Set filter value
plugin.setFilter('name', 'Alice');

// Get current filters
const filters = plugin.getFilters();

// Clear all filters
plugin.clearFilters();

// Clear specific filter
plugin.clearFilter('name');

// Silent mode: update filter state without triggering re-render
// Useful for batching multiple filter changes
plugin.setFilter('name', 'Alice', { silent: true });
plugin.setFilter('dept', 'Engineering'); // last call applies all
```

## Column State Persistence

By default, filter state is **not** included in column state and does not fire `column-state-change`.
Enable `trackColumnState` to opt in:

```ts
features: { filtering: { trackColumnState: true } }
```

When enabled:
- Filter state is included in `getColumnState()` / `columnState` snapshots
- Filter changes fire the `column-state-change` event (debounced)
- `applyColumnState()` / `columnState` restores filter state

This is useful when you want to persist and restore the full grid state (including active filters)
via `localStorage` or a server:

```ts
// Save full state including filters
grid.on('column-state-change', (state) => {
  localStorage.setItem('grid-state', JSON.stringify(state));
});

// Restore state (filters are re-applied automatically)
gridConfig: {
  columnState: JSON.parse(localStorage.getItem('grid-state')),
  features: { filtering: { trackColumnState: true } },
}
```

## Events

```ts
// FilteringFilterEventsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/filtering';

const container = document.getElementById('filtering-filter-events-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, status: 'Active' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, status: 'Active' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, status: 'On Leave' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, status: 'Active' },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000, status: 'Inactive' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000, status: 'Active' },
    { id: 7, name: 'Grace Lee', department: 'Sales', salary: 82000, status: 'Active' },
    { id: 8, name: 'Henry Wilson', department: 'HR', salary: 68000, status: 'Active' },
    { id: 9, name: 'Ivy Chen', department: 'Engineering', salary: 112000, status: 'Active' },
    { id: 10, name: 'Jack Taylor', department: 'Marketing', salary: 78000, status: 'On Leave' },
  ];

  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name' },
      { field: 'department', header: 'Department' },
      { field: 'status', header: 'Status' },
    ],
    features: { filtering: { debounceMs: 300 } },
  };

  grid.rows = sampleData;

  const log = container.querySelector('#filter-event-log');
  const clearBtn = container.querySelector('#clear-filter-log');

  function addLog(type: string, detail: string) {
    if (!log) return;
    const msg = document.createElement('div');
    msg.innerHTML = `<span class="event-type">[${type}]</span> ${detail}`;
    log.insertBefore(msg, log.firstChild);
    while (log.children.length > 15) {
      log.lastChild?.remove();
    }
  }

  clearBtn?.addEventListener('click', () => {
    if (log) log.innerHTML = '';
  });

  grid.on('filter-change', (d) => {
    const filterCount = d.filters?.length || 0;
    const fields = d.filters?.map((f: { field: string }) => f.field).join(', ') || 'none';
    addLog('filter-change', `${filterCount} filter(s) on: ${fields}`);
  });
}
```

The FilteringPlugin emits events when filter state changes. Open filter panels and
apply filters to see the events:

| Event | Description |
| ----- | ----------- |
| `filter-change` | Fired when filters are applied, changed, or cleared |

### `filter-change` Detail

```ts
interface FilterChangeDetail {
  filters: FilterModel[];  // Active filter configurations
}
```

## Styling

The filter panel and inputs support CSS custom properties for theming. Override these on `tbw-grid` or a parent container:

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-filter-panel-bg` | `var(--tbw-color-panel-bg)` | Panel background |
| `--tbw-filter-panel-fg` | `var(--tbw-color-fg)` | Panel text color |
| `--tbw-filter-panel-border` | `var(--tbw-color-border)` | Panel border |
| `--tbw-filter-panel-radius` | `var(--tbw-border-radius)` | Panel border radius |
| `--tbw-filter-panel-shadow` | `var(--tbw-color-shadow)` | Panel shadow |
| `--tbw-filter-input-bg` | `var(--tbw-color-bg)` | Input background |
| `--tbw-filter-input-border` | `var(--tbw-color-border)` | Input border |
| `--tbw-filter-input-focus` | `var(--tbw-color-accent)` | Input focus border |
| `--tbw-filter-active-color` | `var(--tbw-color-accent)` | Active filter indicator |
| `--tbw-filter-btn-padding` | `var(--tbw-button-padding)` | Filter button padding |
| `--tbw-filter-btn-font-weight` | `500` | Filter button font weight |
| `--tbw-filter-btn-min-height` | `auto` | Filter button min height |
| `--tbw-filter-search-padding` | `var(--tbw-spacing-sm) var(--tbw-spacing-md)` | Search input padding |
| `--tbw-filter-item-height` | `28px` | Filter value item height (for virtualization) |
| `--tbw-filter-btn-display` | `inline-flex` | Filter button display (set to `none` to hide) |
| `--tbw-filter-btn-visibility` | `visible` | Filter button visibility |
| `--tbw-panel-padding` | `0.75em` | Panel padding |
| `--tbw-panel-gap` | `0.5em` | Gap between elements |
| `--tbw-animation-duration` | `200ms` | Panel open/close animation |

### Theming Filter Panels

The filter panel is rendered in `document.body` for proper z-index stacking. To apply theme CSS variables:

1. **Add a theme class to the grid** (e.g., `tbw-grid.eds-theme`)
2. **The class is automatically copied** to the filter panel

```css
/* Define theme on a CSS class */
.eds-theme {
  --tbw-filter-panel-bg: #f5f5f5;
  --tbw-filter-btn-padding: 8px 16px;
  --tbw-filter-btn-font-weight: 500;
  --tbw-filter-btn-min-height: 48px;
  --tbw-filter-item-height: 48px;
}
```

```html
<!-- Apply class to grid - it cascades to filter panel -->
<tbw-grid class="eds-theme" ...></tbw-grid>
```

### Hiding Filter Buttons Until Hover

To show filter buttons only when hovering over a column header:

```css
tbw-grid {
  --tbw-filter-btn-visibility: hidden;
}

tbw-grid .header-row .cell:hover .tbw-filter-btn,
tbw-grid .header-row .cell .tbw-filter-btn.active {
  visibility: visible;
}
```

### Example

```css
tbw-grid {
  /* Custom filter panel styling */
  --tbw-filter-panel-bg: #1e1e1e;
  --tbw-filter-panel-fg: #ffffff;
  --tbw-filter-panel-border: #444444;
  --tbw-filter-input-bg: #2d2d2d;
  --tbw-filter-input-border: #555555;
  --tbw-filter-active-color: #4fc3f7;
}
```

### CSS Classes

The filter panel uses these class names for advanced customization:

| Class | Element |
| --- | --- |
| `.tbw-filter-panel` | Dropdown panel container |
| `.tbw-filter-search` | Text search input |
| `.tbw-filter-list` | Options list container |
| `.tbw-filter-option` | Individual filter option |
| `.tbw-filter-option.selected` | Selected option |
| `.tbw-filter-buttons` | Action button group |
| `.tbw-filter-clear` | Clear filter button |
| `.tbw-filter-apply` | Apply filter button |

## Row Insertion with Active Filters

When filtering is active, assigning `rows` automatically re-filters the data — so a
newly inserted row may be hidden if it doesn't match the current filter. If you want
the row to appear exactly where you placed it (e.g., after a user clicks "Add Row"),
use `insertRow()`:

```ts
grid.insertRow(3, newRow); // stays at visible index 3, auto-animates
```

The row is also added to source data, so the next full `grid.rows = freshData`
assignment re-filters normally. See the
[API Reference → Insert & Remove Rows](/grid/api-reference.md#insert--remove-rows)
for full details.

:::tip
Do **not** use `insertRow()` for data refreshes (API responses,
WebSocket updates). In those cases just set `grid.rows = newData` and let
the filter re-apply.
:::

## See Also

- **[Multi-Sort](/grid/plugins/multi-sort.md)** — Multi-column sorting
- **[Server-Side Data](../server-side/)** — Server-side filtering via `filterHandler`
- **[Selection](/grid/plugins/selection.md)** — Row and cell selection
- **[Common Patterns](/grid/guides/common-patterns.md)** — Full application recipes using filtering
- **[Plugins Overview](/grid/plugins.md)** — Plugin compatibility and combinations

---

# Column Grouping Plugin

> Group columns visually under shared parent headers.

The Column Grouping plugin enables visual grouping of columns under shared headers.

## Installation

```ts
import '@toolbox-web/grid/features/grouping-columns';
```

## Basic Usage

There are three ways to define column groups, from most to least recommended:

### Option 1: Feature config `columnGroups` (Recommended)

Define everything in one place — groups, renderers, and plugin behavior:

#### Angular

```typescript
import { GridGroupingColumnsDirective } from '@toolbox-web/grid-angular/features/grouping-columns';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridGroupingColumnsDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [groupingColumns]="{
        columnGroups: [
          { header: 'Personal Info', children: ['firstName', 'lastName', 'email'] },
          { header: 'Work Info', children: ['department', 'title', 'salary'] },
        ]
      }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [...];

  columns: ColumnConfig[] = [
    { field: 'firstName', header: 'First Name' },
    { field: 'lastName', header: 'Last Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
    { field: 'title', header: 'Title' },
    { field: 'salary', header: 'Salary' },
  ];
}
```

:::tip[Auto-generated IDs]
The `id` property on each group is optional. When omitted, it is auto-generated as a slug of the `header` (e.g. `'Personal Info'` → `'personal-info'`). Provide an explicit `id` when you need a stable identifier for programmatic access or custom renderers.
:::

### Option 2: Grid config `columnGroups`

If your groups are part of a server-provided layout or shared data model, define them on `gridConfig.columnGroups`:

```ts
grid.gridConfig = {
  columnGroups: [
    { header: 'Personal Info', children: ['firstName', 'lastName', 'email'] },
    { header: 'Work Info', children: ['department', 'title', 'salary'] },
  ],
  columns: [...],
  features: { groupingColumns: true },
};
```

:::note[Precedence]
If `columnGroups` is defined in **both** the feature config and `gridConfig`, the feature config wins and a console warning is emitted.
:::

### Option 3: Inline `group` property

For simple cases, assign group membership directly on each column. The `group` string becomes the group id:

```ts
grid.gridConfig = {
  columns: [
    { field: 'firstName', header: 'First Name', group: 'personal' },
    { field: 'lastName', header: 'Last Name', group: 'personal' },
    { field: 'department', header: 'Department', group: 'work' },
  ],
  features: { groupingColumns: true },
};
```

You can also pass an object with an explicit label:

```ts
{ field: 'firstName', header: 'First Name', group: { id: 'personal', label: 'Personal Info' } }
```

:::caution
The inline `group` property is strictly for declaring group membership. It does not support custom renderers — use `columnGroups` with `renderer` or `groupHeaderRenderer` for that.
:::

## Demos

### Default Column Groups

```ts
// GroupingColumnsDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/grouping-columns';

const container = document.getElementById('grouping-columns-default-demo');
if (container) {
  const firstNames = ['Alice', 'Bob', 'Carol', 'David', 'Emma', 'Frank', 'Grace', 'Henry', 'Ivy', 'Jack'];
  const lastNames = ['Johnson', 'Smith', 'Williams', 'Brown', 'Davis', 'Miller', 'Wilson', 'Moore', 'Taylor', 'Anderson'];
  const departments = ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'];
  const titlesByDept = {
    Engineering: ['Senior Engineer', 'Software Engineer', 'Lead Engineer', 'DevOps Engineer', 'QA Engineer'],
    Marketing: ['Marketing Manager', 'Content Writer', 'Brand Manager', 'SEO Specialist'],
    Sales: ['Sales Rep', 'Sales Manager', 'Account Executive'],
    HR: ['HR Manager', 'Recruiter', 'Training Coordinator'],
    Finance: ['Accountant', 'Financial Analyst', 'Controller'],
  };
  function generateData(count: number) {
    return Array.from({ length: count }, (_, i) => {
      const firstName = firstNames[i % firstNames.length];
      const lastName = lastNames[i % lastNames.length];
      const department = departments[i % departments.length];
      const titles = titlesByDept[department];
      const title = titles[i % titles.length];
      return {
        id: i + 1,
        firstName,
        lastName,
        email: `${firstName.toLowerCase()}@example.com`,
        department,
        title,
        salary: 50000 + Math.floor((i * 3456) % 70000),
      };
    });
  }

  const sampleData = generateData(20);
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'firstName', header: 'First Name', group: { id: 'personal', label: 'Personal Info' } },
    { field: 'lastName', header: 'Last Name', group: { id: 'personal', label: 'Personal Info' } },
    { field: 'email', header: 'Email', group: { id: 'personal', label: 'Personal Info' } },
    { field: 'department', header: 'Department', group: { id: 'work', label: 'Work Info' } },
    { field: 'title', header: 'Title', group: { id: 'work', label: 'Work Info' } },
    { field: 'salary', header: 'Salary', type: 'number', group: { id: 'work', label: 'Work Info' } },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(showGroupBorders = true) {
    grid.gridConfig = {
      columns,
      features: { groupingColumns: { showGroupBorders } },
    };
    grid.rows = sampleData;
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues.showGroupBorders as boolean);
  }) as EventListener);
}
```

### Custom Group Header Renderer

Use `groupHeaderRenderer` to customize the content of group header cells. The renderer is called once per group, receives a `GroupHeaderRenderParams` object (including the group `id`), and can return an `HTMLElement`, an HTML string, or `void` to keep the default label.

HTML strings returned from the renderer are automatically sanitized (scripts and event-handler attributes are stripped) — see [Production Checklist › Security](/grid/guides/production-checklist.md#security).

Since the renderer receives `params.id`, a single function can differentiate rendering per group:

#### Angular

You can pass a component class as the renderer. The adapter bridges it automatically.

```typescript
import { GridGroupingColumnsDirective } from '@toolbox-web/grid-angular/features/grouping-columns';
import { Component, input } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

// Group header component — receives params as inputs
@Component({
  selector: 'app-group-header',
  template: `{{ icon() }} <strong>{{ label() }}</strong> ({{ columns().length }})`,
})
export class GroupHeaderComponent {
  id = input.required<string>();
  label = input.required<string>();
  columns = input.required<ColumnConfig[]>();
  firstIndex = input.required<number>();
  isImplicit = input.required<boolean>();

  private icons: Record<string, string> = {
    'personal-info': '👤',
    'work-info': '💼',
  };

  icon = () => this.icons[this.id()] ?? '📁';
}

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridGroupingColumnsDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [groupingColumns]="groupingConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [...];
  columns = [...];

  groupingConfig = {
    columnGroups: [
      { header: 'Personal Info', children: ['firstName', 'lastName', 'email'] },
      { header: 'Work Info', children: ['department', 'title', 'salary'] },
    ],
    groupHeaderRenderer: GroupHeaderComponent,
  };
}
```

You can also define a `renderer` directly on individual group definitions. A per-group renderer takes precedence over `groupHeaderRenderer` for that specific group:

#### Angular

Per-group renderers can also be component classes:

```typescript
import { GridGroupingColumnsDirective } from '@toolbox-web/grid-angular/features/grouping-columns';
import { Component, input } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-personal-group-header',
  template: `👤 <strong>{{ label() }}</strong>`,
})
export class PersonalGroupHeaderComponent {
  id = input.required<string>();
  label = input.required<string>();
  columns = input.required<ColumnConfig[]>();
  firstIndex = input.required<number>();
  isImplicit = input.required<boolean>();
}

@Component({
  selector: 'app-default-group-header',
  template: `<strong>{{ label() }}</strong>`,
})
export class DefaultGroupHeaderComponent {
  id = input.required<string>();
  label = input.required<string>();
  columns = input.required<ColumnConfig[]>();
  firstIndex = input.required<number>();
  isImplicit = input.required<boolean>();
}

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridGroupingColumnsDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [groupingColumns]="groupingConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [...];
  columns = [...];

  groupingConfig = {
    columnGroups: [
      {
        header: 'Personal Info',
        children: ['firstName', 'lastName', 'email'],
        renderer: PersonalGroupHeaderComponent,
      },
      { header: 'Work Info', children: ['department', 'title', 'salary'] },
    ],
    // Fallback for groups without their own renderer
    groupHeaderRenderer: DefaultGroupHeaderComponent,
  };
}
```

```ts
// GroupingColumnsCustomRendererDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/grouping-columns';

const container = document.getElementById('grouping-columns-custom-renderer-demo');
if (container) {
  const firstNames = ['Alice', 'Bob', 'Carol', 'David', 'Emma', 'Frank', 'Grace', 'Henry', 'Ivy', 'Jack'];
  const lastNames = ['Johnson', 'Smith', 'Williams', 'Brown', 'Davis', 'Miller', 'Wilson', 'Moore', 'Taylor', 'Anderson'];
  const departments = ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'];
  const titlesByDept: Record<string, string[]> = {
    Engineering: ['Senior Engineer', 'Software Engineer', 'Lead Engineer', 'DevOps Engineer', 'QA Engineer'],
    Marketing: ['Marketing Manager', 'Content Writer', 'Brand Manager', 'SEO Specialist'],
    Sales: ['Sales Rep', 'Sales Manager', 'Account Executive'],
    HR: ['HR Manager', 'Recruiter', 'Training Coordinator'],
    Finance: ['Accountant', 'Financial Analyst', 'Controller'],
  };

  function generateData(count: number) {
    return Array.from({ length: count }, (_, i) => {
      const firstName = firstNames[i % firstNames.length];
      const lastName = lastNames[i % lastNames.length];
      const department = departments[i % departments.length];
      const titles = titlesByDept[department];
      const title = titles[i % titles.length];
      return {
        id: i + 1,
        firstName,
        lastName,
        email: `${firstName.toLowerCase()}@example.com`,
        department,
        title,
        salary: 50000 + Math.floor((i * 3456) % 70000),
      };
    });
  }

  const sampleData = generateData(20);
  const columns = [
    { field: 'id', header: 'ID', type: 'number' as const },
    { field: 'firstName', header: 'First Name', group: { id: 'personal', label: 'Personal Info' } },
    { field: 'lastName', header: 'Last Name', group: { id: 'personal', label: 'Personal Info' } },
    { field: 'email', header: 'Email', group: { id: 'personal', label: 'Personal Info' } },
    { field: 'department', header: 'Department', group: { id: 'work', label: 'Work Info' } },
    { field: 'title', header: 'Title', group: { id: 'work', label: 'Work Info' } },
    { field: 'salary', header: 'Salary', type: 'number' as const, group: { id: 'work', label: 'Work Info' } },
  ];

  const icons: Record<string, string> = {
    personal: '👤',
    work: '💼',
  };

  const grid = queryGrid('tbw-grid', container)!;
  grid.gridConfig = {
    columns,
    features: {
      groupingColumns: {
        groupHeaderRenderer: (params) => {
          const icon = icons[params.id] ?? '📁';
          const el = document.createElement('span');
          el.style.cssText = 'display: flex; align-items: center; gap: 0.4em;';
          el.innerHTML = `<span>${icon}</span> <strong>${params.label}</strong> <span style="opacity: 0.6; font-size: 0.85em;">(${params.columns.length} columns)</span>`;
          return el;
        },
      },
    },
  };
  grid.rows = sampleData;
}
```

## Configuration Options

### Where to configure what

| What | Where | Notes |
| --- | --- | --- |
| Group definitions | `features.groupingColumns.columnGroups` | Recommended — keeps everything in one place |
| Group definitions (alt) | `gridConfig.columnGroups` | Useful for server-driven layouts |
| Group membership | `columns[].group` | Simplest — just assigns a column to a group |
| Custom rendering | `groupHeaderRenderer` or per-group `renderer` | On the feature config or group definition |
| Plugin behavior | `showGroupBorders`, `lockGroupOrder` | On the feature config |

### Type reference

- **Plugin options**: [`GroupingColumnsConfig`](./interfaces/groupingcolumnsconfig/) — `columnGroups`, `groupHeaderRenderer`, `showGroupBorders`, `lockGroupOrder`
- **Group definition**: [`ColumnGroupDefinition`](./interfaces/columngroupdefinition/) — `id` (optional), `header`, `children`, `renderer`
- **Renderer params**: [`GroupHeaderRenderParams`](./interfaces/groupheaderrenderparams/) — `id`, `label`, `columns`, `firstIndex`, `isImplicit`
- **Runtime group data**: [`ColumnGroup`](./interfaces/columngroup/) — computed group objects returned by `getGroups()`
- **Column config `group`**: `string` (group ID) or `{ id: string; label?: string }`

## Programmatic API

The plugin provides these methods on the plugin instance:

```ts
const plugin = grid.getPluginByName('groupingColumns');

// Check if grouping is active
plugin.isGroupingActive(); // boolean

// Get all computed groups
plugin.getGroups(); // ColumnGroup[]

// Get columns in a specific group
plugin.getGroupColumns('personal'); // ColumnConfig[]

// Force refresh of column groups
plugin.refresh();
```
## Usage with Column Reordering

When using `GroupingColumnsPlugin` together with the [Reorder Columns](../reorder-columns/) plugin, column reordering does not enforce group boundaries by default. Users can drag columns out of their groups, and when they do, the group **fragments** — each contiguous run of columns belonging to the same group gets its own header cell. If the user drags the columns back together, the group header merges automatically.

This means groups never "break" — they split into fragments that remain visually connected to their group identity. Utility columns (like selection checkboxes or row numbers) that land between two fragments of the same group are visually absorbed into the surrounding group header.

Group header cells are also draggable — dragging a group header moves all columns in that fragment as a block. If a group is fragmented, each fragment can be dragged independently. The [Visibility Panel](../visibility/) also reflects fragmented groups, showing each fragment as a separate section in the column list.

### Built-in: `lockGroupOrder`

Set `lockGroupOrder: true` to automatically prevent columns from being moved outside their group:

```ts
grid.gridConfig = {
  features: {
    groupingColumns: { lockGroupOrder: true },
  },
};
```

This blocks moves that would break group contiguity in both header drag-and-drop and the visibility panel.

### Manual: `column-move` Event

For more control, the `column-move` event is **cancelable**, so you can implement custom validation:

```ts
grid.on('column-move', ({ field, fromIndex, toIndex, columnOrder }, e) => {

  // Example: prevent moves that break group boundaries
  if (!isValidMoveWithinGroup(field, fromIndex, toIndex)) {
    e.preventDefault(); // Column snaps back to original position
    return;
  }

  // Persist the new order
  saveColumnOrder(columnOrder);
});
```

The `column-move` event includes the complete `columnOrder` array, making it easy to persist user preferences.

## Styling

The column grouping plugin supports CSS custom properties for theming. Override these on `tbw-grid` or a parent container:

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-grouping-columns-header-bg` | `var(--tbw-color-header-bg)` | Group header row background |
| `--tbw-grouping-columns-border` | `var(--tbw-color-border)` | Group borders |
| `--tbw-grouping-columns-separator` | `var(--tbw-color-border-strong)` | Separator between groups |
| `--tbw-button-padding-sm` | `0.25rem 0.5rem` | Group header cell padding |
| `--tbw-font-size-sm` | `0.9285em` | Group header font size |

### Example

```css
tbw-grid {
  /* Custom column grouping styling */
  --tbw-grouping-columns-header-bg: #e3f2fd;
  --tbw-grouping-columns-border: #90caf9;
  --tbw-grouping-columns-separator: #1976d2;
}
```

### CSS Classes

The column grouping plugin uses these class names:

| Class | Element |
| --- | --- |
| `.header-group-row` | Group header row container |
| `.header-group-row.no-borders` | Borderless mode |
| `.header-group-cell` | Individual group header cell |
| `.header-row .cell.grouped` | Column under a group |
| `.header-row .cell.group-end` | Last column in a group |

## Integration with Exports

When the [ExportPlugin](../export/) is installed alongside grouping columns, group headers automatically appear in **Excel** and **JSON** exports (since 2.10.0). CSV stays flat. See [Column Groups in Exports](../export/#column-groups-in-exports) for the full behaviour matrix.

The mechanism is the generic `collectHeaderRows` plugin query — any plugin can contribute extra header rows the same way. Style group rows independently via `excelStyles.groupHeaderStyle`.

## See Also

- **[Export](../export/)** — Column groups appear in Excel/JSON exports
- **[Row Grouping](../grouping-rows/)** — Group rows by field values
- **[Pinned Columns](../pinned-columns/)** — Sticky columns
- **[Reorder Columns](../reorder-columns/)** — Drag-and-drop column reordering

---

# Row Grouping Plugin

> Group rows by column values with expandable groups.

The Row Grouping plugin organizes your rows into collapsible hierarchical groups. Perfect for organizing data by category, department, status, or any other dimension—or even multiple dimensions for nested grouping.

## Installation

```ts
import '@toolbox-web/grid/features/grouping-rows';
```

## Basic Usage

The `groupOn` callback receives each row and should return an array representing the group path. For single-level grouping, return a one-element array. For multi-level grouping, return multiple elements (e.g., `['Region', 'Department']`).

#### Angular

```typescript
// Feature import - enables the [groupingRows] input
import { GridGroupingRowsDirective } from '@toolbox-web/grid-angular/features/grouping-rows';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid, GridGroupingRowsDirective],
  template: `
    <tbw-grid
      [rows]="employees"
      [columns]="columns"
      [groupingRows]="groupingConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class EmployeeGridComponent {
  employees = [/* employee data */];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Employee' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'currency' }
  ];

  groupingConfig = {
    groupOn: (row: any) => [row.department],
    showRowCount: true,
  };
}
```

## Demos

### Default Grouping

```ts
// GroupingRowsDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/grouping-rows';

const container = document.getElementById('grouping-rows-default-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice', department: 'Engineering', salary: 95000 },
    { id: 2, name: 'Bob', department: 'Marketing', salary: 75000 },
    { id: 3, name: 'Carol', department: 'Engineering', salary: 105000 },
    { id: 4, name: 'Dan', department: 'Sales', salary: 85000 },
    { id: 5, name: 'Eve', department: 'Marketing', salary: 72000 },
    { id: 6, name: 'Frank', department: 'Engineering', salary: 98000 },
    { id: 7, name: 'Grace', department: 'Sales', salary: 88000 },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'number' },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(opts: Record<string, unknown>) {
    const accordion = opts.accordion as boolean ?? false;
    const expandRaw = opts.defaultExpanded as string;
    const defaultExpanded = accordion && expandRaw === 'all' ? false
      : expandRaw === 'all' ? true
      : expandRaw === 'none' ? false
      : expandRaw;

    grid.gridConfig = {
      columns,
      features: {
        groupingRows: {
          animation: (opts.animation as string) ?? 'slide',
          groupOn: (row: { department: string }) => row.department,
          defaultExpanded,
          showRowCount: opts.showRowCount as boolean ?? true,
          indentWidth: (opts.indentWidth as number) ?? 20,
          fullWidth: true,
          accordion,
        } as any,
      },
    };
    grid.rows = sampleData;
  }

  rebuild({ animation: 'slide', defaultExpanded: 'none', showRowCount: true, accordion: false, indentWidth: 20 });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues);
  }) as EventListener);
}
```

### Custom Group Row Renderer

Use `groupRowRenderer` to take full control of the group row's contents. The renderer receives a `GroupRowRenderParams` object (`key`, `value`, `depth`, `rows`, `expanded`, `toggleExpand`) and can return an `HTMLElement`, an HTML string, or `void` to keep the default rendering. The framework adapters accept their native return types (`ReactNode`, `VNode`, or a component `Type`) and bridge them automatically.

#### Angular

Pass a component class — the adapter bridges it and binds the params as inputs.

```typescript
import { GridGroupingRowsDirective } from '@toolbox-web/grid-angular/features/grouping-rows';
import { Component, input } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  selector: 'app-group-row',
  template: `
    <button type="button" (click)="toggleExpand()">
      {{ expanded() ? '▼' : '▶' }} <strong>{{ value() }}</strong> ({{ rows().length }})
    </button>
  `,
})
export class GroupRowComponent {
  key = input.required<string>();
  value = input.required<unknown>();
  depth = input.required<number>();
  rows = input.required<unknown[]>();
  expanded = input.required<boolean>();
  toggleExpand = input.required<() => void>();
}

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridGroupingRowsDirective],
  template: `
    <tbw-grid
      [rows]="employees"
      [columns]="columns"
      [groupingRows]="groupingConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  groupingConfig = {
    groupOn: (row: any) => [row.department],
    groupRowRenderer: GroupRowComponent,
  };
}
```

## Configuration Options

See [`GroupingRowsConfig`](./interfaces/groupingrowsconfig/) for the full list of options and their defaults.

### Default Expanded Options

The `defaultExpanded` option controls which groups are expanded on initial render:

```ts
// Expand all groups
features: { groupingRows: { defaultExpanded: true, groupOn: ... } }

// Collapse all groups (default)
features: { groupingRows: { defaultExpanded: false, groupOn: ... } }

// Expand group at index 0
features: { groupingRows: { defaultExpanded: 0, groupOn: ... } }

// Expand group with specific key
features: { groupingRows: { defaultExpanded: 'Engineering', groupOn: ... } }

// Expand multiple groups by key
features: { groupingRows: { defaultExpanded: ['Engineering', 'Sales'], groupOn: ... } }
```

:::note
When using `accordion: true`, prefer `defaultExpanded` with a single value
(number or string) rather than `true` or an array with multiple values.
:::

### Animation Options

The `animation` option controls how grouped rows appear/disappear:

```ts
// Slide animation (default)
features: { groupingRows: { animation: 'slide', ... } }

// Fade animation
features: { groupingRows: { animation: 'fade', ... } }

// No animation
features: { groupingRows: { animation: false, ... } }
```

:::note
Animation respects the grid-level `animation.mode` setting.
:::

### Accordion Mode

In accordion mode, only one group can be expanded at a time. Expanding a group automatically collapses all sibling groups at the same depth level.

```ts
features: {
  groupingRows: {
    groupOn: (row) => row.department,
    accordion: true, // Only one group open at a time
  },
},
```

### Aggregators

```ts
// GroupingRowsWithAggregatorsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/grouping-rows';

const container = document.getElementById('grouping-rows-with-aggregators-demo');
if (container) {
  // Sample data for grouping demos
  const sampleData = [
    { id: 1, name: 'Alice', department: 'Engineering', salary: 95000 },
    { id: 2, name: 'Bob', department: 'Marketing', salary: 75000 },
    { id: 3, name: 'Carol', department: 'Engineering', salary: 105000 },
    { id: 4, name: 'Dan', department: 'Sales', salary: 85000 },
    { id: 5, name: 'Eve', department: 'Marketing', salary: 72000 },
    { id: 6, name: 'Frank', department: 'Engineering', salary: 98000 },
    { id: 7, name: 'Grace', department: 'Sales', salary: 88000 },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'number' },
  ];

  const grid = queryGrid('tbw-grid', container);

      grid.gridConfig = {
        columns,
        features: {
          groupingRows: {
            groupOn: (row: { department: string }) => row.department,
            defaultExpanded: false,
            showRowCount: true,
            indentWidth: 20,
            aggregators: {
              salary: 'sum',
            },
          },
        },
      };
      grid.rows = sampleData;
}
```

Display aggregate values (sum, avg, count, min, max, first, last) in group headers. Works in both full-width and per-column rendering modes.

```ts
features: {
  groupingRows: {
    groupOn: (row) => row.department,
    aggregators: {
      salary: 'sum',    // Sum of salaries in each group
      bonus: 'avg',     // Average bonus
      id: 'count',      // Count of rows
    },
  },
},
```

**Built-in aggregators:**
- `sum` - Sum of numeric values
- `avg` - Average of numeric values
- `count` - Number of rows
- `min` - Minimum value
- `max` - Maximum value
- `first` - First row's value
- `last` - Last row's value

You can also provide a custom aggregator function:

```ts
aggregators: {
  salary: (rows, field) => {
    const total = rows.reduce((sum, r) => sum + r[field], 0);
    return `$${total.toLocaleString()}`;
  },
}
```

## Multi-Level Grouping

Return multiple values from `groupOn` to create nested group hierarchies. Row counts display correctly at every depth level.

```ts
// GroupingRowsMultiLevelDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/grouping-rows';

const container = document.getElementById('grouping-rows-multi-level-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice', country: 'USA', department: 'Engineering', salary: 95000 },
    { id: 2, name: 'Bob', country: 'USA', department: 'Marketing', salary: 75000 },
    { id: 3, name: 'Carol', country: 'USA', department: 'Engineering', salary: 105000 },
    { id: 4, name: 'Dan', country: 'UK', department: 'Sales', salary: 85000 },
    { id: 5, name: 'Eve', country: 'UK', department: 'Marketing', salary: 72000 },
    { id: 6, name: 'Frank', country: 'USA', department: 'Sales', salary: 98000 },
    { id: 7, name: 'Grace', country: 'UK', department: 'Sales', salary: 88000 },
    { id: 8, name: 'Henry', country: 'Germany', department: 'Engineering', salary: 92000 },
    { id: 9, name: 'Ivy', country: 'Germany', department: 'Engineering', salary: 110000 },
    { id: 10, name: 'Jack', country: 'UK', department: 'Engineering', salary: 78000 },
  ];

  const grid = queryGrid('tbw-grid', container)!;
  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 60 },
      { field: 'name', header: 'Name' },
      { field: 'country', header: 'Country' },
      { field: 'department', header: 'Department' },
      { field: 'salary', header: 'Salary', type: 'number', align: 'right' },
    ],
    features: {
      groupingRows: {
        groupOn: (row: { country: string; department: string }) => [row.country, row.department],
        defaultExpanded: true,
        showRowCount: true,
      } as any,
    },
  };
  grid.rows = sampleData;
}
```

```ts
features: {
  groupingRows: {
    groupOn: (row) => [row.region, row.department, row.team],
  },
},
```

## Programmatic API

See [`GroupingRowsPlugin`](./classes/groupingrowsplugin/) for the full list of methods.

```ts
const plugin = grid.getPluginByName('groupingRows');

plugin.expand('Engineering');
plugin.collapse('Engineering');
plugin.toggle('Engineering');
plugin.expandAll();
plugin.collapseAll();
plugin.isExpanded('Engineering');    // boolean
plugin.getExpandedGroups();          // string[]
plugin.setGroupOn((row) => [row.region, row.department]);
// Optionally pass an initial expansion that resolves against the *new* groups
// (issue #335). Avoids the stale-snapshot race when chaining setGroupOn → expandAll.
plugin.setGroupOn((row) => row.counterparty, true);
plugin.setGroupOn((row) => row.region, ['EMEA', 'AMER']);
plugin.refreshGroups();
```

## Styling

The row grouping plugin supports CSS custom properties for theming. Override these on `tbw-grid` or a parent container:

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-group-indent-width` | `1.25em` (~20px) | Indentation per group level |
| `--tbw-grouping-rows-bg` | `var(--tbw-color-panel-bg)` | Group row background |
| `--tbw-grouping-rows-bg-hover` | `var(--tbw-color-row-hover)` | Group row hover |
| `--tbw-grouping-rows-toggle-hover` | `var(--tbw-color-row-hover)` | Toggle button hover |
| `--tbw-grouping-rows-count-color` | `var(--tbw-color-fg-muted)` | Count badge color |
| `--tbw-grouping-rows-aggregate-color` | `var(--tbw-color-fg-muted)` | Aggregate value color |
| `--tbw-toggle-size` | `1.25em` | Toggle button size |
| `--tbw-font-size-xs` | `0.7857em` | Count text size |
| `--tbw-animation-duration` | `200ms` | Expand/collapse animation |
| `--tbw-animation-easing` | `ease-out` | Animation curve |

### Example

```css
tbw-grid {
  /* Custom row grouping styling */
  --tbw-group-indent-width: 1.5em; /* Wider indentation */
  --tbw-grouping-rows-bg: #e8f5e9;
  --tbw-grouping-rows-bg-hover: #c8e6c9;
  --tbw-grouping-rows-count-color: #388e3c;
}
```

### CSS Classes

The row grouping plugin uses these class names:

| Class | Element |
| --- | --- |
| `.group-row` | Group header row |
| `.group-toggle` | Expand/collapse button |
| `.group-label` | Group name and value |
| `.group-count` | Row count badge |
| `.group-aggregates` | Container for aggregate values |
| `.group-aggregate` | Individual aggregate value |
| `.tbw-group-slide-in` | Child row slide animation |
| `.tbw-group-fade-in` | Child row fade animation |
| `[data-group-depth="N"]` | Group nesting level (0-4) |
| `.tbw-row-expanded` | Applied to a `.group-row` while it is expanded. Use this for theming expanded group rows instead of `[aria-expanded="true"]`. |

## Events

| Event            | Detail                                         | Description                                  |
| ---------------- | ---------------------------------------------- | -------------------------------------------- |
| `group-toggle`   | `{ key, expanded, value, depth }`              | Fired when a group is expanded/collapsed     |
| `group-expand`   | `{ groupKey, groupPath }`                      | Fired when a pre-defined group is expanded   |
| `group-collapse` | `{ groupKey, groupPath }`                      | Fired when a pre-defined group is collapsed  |

## Server-Side Data

> **Requires:** `ServerSidePlugin` — [see Server-Side Plugin](/grid/plugins/server-side.md)

For server-side scenarios where group structure is fetched from the server and rows are loaded on demand, use `ServerSidePlugin` alongside Row Grouping. ServerSide returns group definitions as root data; when the user expands a group, the plugin fetches group rows via `getChildRows()`.

#### Angular

```typescript
import { GridGroupingRowsDirective } from '@toolbox-web/grid-angular/features/grouping-rows';
import { GridServerSideDirective } from '@toolbox-web/grid-angular/features/server-side';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-server-grouped-grid',
  imports: [Grid, GridGroupingRowsDirective, GridServerSideDirective],
  template: `
    <tbw-grid
      [columns]="columns"
      [serverSide]="serverSideConfig"
      [groupingRows]="true"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class ServerGroupedGridComponent {
  columns: ColumnConfig[] = [
    { field: 'name', header: 'Employee' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'currency' },
  ];

  serverSideConfig = {
    pageSize: 50,
    dataSource: {
      async getRows(params: any) {
        const res = await fetch(`/api/groups?start=${params.startNode}&end=${params.endNode}`);
        return res.json();
      },
      async getChildRows(params: any) {
        const { groupKey } = params.context;
        const res = await fetch(`/api/groups/${groupKey}/rows`);
        return { rows: await res.json() };
      },
    },
  };
}
```

**Data flow:**
1. ServerSide fetches block → broadcasts `datasource:data`
2. GroupingRowsPlugin claims data as pre-defined groups
3. On group expand → fires `datasource:fetch-children` with `{ source: 'grouping-rows', groupKey }`
4. ServerSide calls `getChildRows()` → broadcasts `datasource:children`
5. GroupingRowsPlugin receives rows and renders them under the group

:::note
Child rows are fetched as a single batch — no pagination. If a group has many rows, limit the response server-side.
:::

### Standalone Mode (Without ServerSide)

If `ServerSidePlugin` is not loaded, use the imperative API to provide groups and rows directly:

```ts
import '@toolbox-web/grid/features/grouping-rows';
import { queryGrid } from '@toolbox-web/grid';

const grid = await queryGrid('tbw-grid', true);
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Employee' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'currency' },
  ],
  features: {
    groupingRows: true,
  },
};

const grouping = grid.getPluginByName('groupingRows');

// Lazy-load rows when a group is expanded
grid.on('group-expand', async ({ groupKey }) => {
  grouping.setGroupLoading(groupKey, true);
  const rows = await fetchGroupRows(groupKey);
  grouping.setGroupRows(groupKey, rows); // also clears loading state
});

// Load groups asynchronously
const groups = await fetch('/api/groups').then(r => r.json());
grouping.setGroups(groups);
```

:::note
`setGroupRows()` automatically clears the loading indicator — no need to call `setGroupLoading(key, false)` afterwards.
:::

| Method | Description |
| --- | --- |
| `setGroups(groups)` | Replace groups with an external structure |
| `getGroups()` | Get the current group definitions |
| `setGroupRows(key, rows)` | Populate rows for an expanded group |
| `setGroupLoading(key, loading)` | Toggle loading indicator for a group |
| `clearGroupRows(key?)` | Clear cached rows (specific group or all) |

### Nested Pre-Defined Groups

Groups can be nested using the `children` property:

```ts
const groups: GroupDefinition[] = [
  {
    key: 'engineering',
    value: 'Engineering',
    rowCount: 150,
    children: [
      { key: 'frontend', value: 'Frontend', rowCount: 60 },
      { key: 'backend', value: 'Backend', rowCount: 90 },
    ],
  },
];
```

## Plugin Compatibility

:::caution[Incompatible Plugins]
The Row Grouping plugin **cannot** be used with the following plugins:

- **[Tree](/grid/plugins/tree.md)** — Both plugins transform the entire row model. Tree flattens nested hierarchies while Row Grouping groups flat rows with synthetic headers. Use one approach per grid.
- **[Pivot](/grid/plugins/pivot.md)** — Pivot creates its own aggregated row and column structure. Row grouping cannot be applied on top of pivot-generated rows.
:::

A development-mode warning is shown if incompatible plugins are loaded together.

## See Also

- **[Column Groups](../grouping-columns/)** — Group column headers
- **[Tree](/grid/plugins/tree.md)** — Hierarchical tree data
- **[Pivot](/grid/plugins/pivot.md)** — Pivot table with grouping
- **[Common Patterns](/grid/guides/common-patterns.md)** — Application recipes using grouping
- **[Plugins Overview](/grid/plugins.md)** — Plugin compatibility and combinations

---

# Master-Detail Plugin

> Show expandable detail rows beneath data rows.

The Master-Detail plugin lets you create expandable detail rows that reveal additional content beneath each master row. Perfect for order/line-item UIs, employee/department views, or any scenario where you need to show related data without navigating away.

## Installation

```ts
import '@toolbox-web/grid/features/master-detail';
```

## Basic Usage

The key configuration is `detailRenderer` - a function that receives the row data and returns either an HTML string or a DOM element. This gives you complete control over what appears in the expanded detail area.

#### Angular

```typescript
// Feature imports - GridMasterDetailDirective owns the [masterDetail] input,
// GridDetailView is the structural directive used inside <tbw-grid> for templating.
import {
  GridMasterDetailDirective,
  GridDetailView,
} from '@toolbox-web/grid-angular/features/master-detail';

import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-order-grid',
  imports: [Grid, GridMasterDetailDirective, GridDetailView],
  template: `
    <tbw-grid
      [rows]="orders"
      [columns]="columns"
      [masterDetail]="true"
      style="height: 400px; display: block;">
      <ng-template tbwDetailView let-row let-toggle="toggle">
        <div class="order-details">
          <h4>Order Items</h4>
          <ul>
            <li *ngFor="let item of row.items">
              {{ item.name }} - \${{ item.price }}
            </li>
          </ul>
          <button (click)="toggle()">Close</button>
        </div>
      </ng-template>
    </tbw-grid>
  `,
})
export class OrderGridComponent {
  orders = [/* order data */];

  columns: ColumnConfig[] = [
    { field: 'orderId', header: 'Order ID' },
    { field: 'customer', header: 'Customer' },
    { field: 'total', header: 'Total', type: 'currency' }
  ];
}
```

Use the [`GridDetailView`](/grid/angular/api/directives/griddetailview.md) directive
(`<ng-template tbwDetailView>`) for Angular-idiomatic detail panels with
template context (`let-row`, `let-toggle="toggle"`). For non-Angular consumers
of the same plugin, an inline `detailRenderer: (row) => HTMLElement | string`
is also accepted in `gridConfig.masterDetail`.

## Demos

### Default Master-Detail

```ts
// MasterDetailDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/master-detail';

const container = document.getElementById('master-detail-default-demo');
if (container) {
  const generateOrderData = (count: number) => {
    const customers = ['Alice Corp', 'Bob Inc', 'Carol LLC', 'Delta Co', 'Echo Ltd', 'Foxtrot GmbH', 'Golf SA', 'Hotel AG'];
    const products = ['Widget A', 'Widget B', 'Gadget X', 'Gadget Y', 'Service Plan', 'Support Pack', 'License', 'Hardware Kit'];
    return Array.from({ length: count }, (_, i) => {
      const itemCount = 1 + (i % 4);
      const items = Array.from({ length: itemCount }, (_, j) => ({
        name: products[(i + j) % products.length],
        qty: 1 + ((i + j) % 5),
        price: 25 + ((i * 7 + j * 13) % 200),
      }));
      return {
        id: 1001 + i,
        customer: customers[i % customers.length],
        date: `2024-${String(1 + (i % 12)).padStart(2, '0')}-${String(1 + (i % 28)).padStart(2, '0')}`,
        total: items.reduce((sum, item) => sum + item.qty * item.price, 0),
        items,
      };
    });
  };

  const columns = [
    { field: 'id', header: 'Order ID', type: 'number' },
    { field: 'customer', header: 'Customer' },
    { field: 'date', header: 'Date' },
    { field: 'total', header: 'Total', type: 'number', format: (v: number) => `$${v.toFixed(2)}` },
  ];

  const detailRenderer = (row: { items: { name: string; qty: number; price: number }[] }) => {
    const div = document.createElement('div');
    div.style.cssText = 'padding: 16px;';
    div.innerHTML = `
      <h4 style="margin: 0 0 8px;">Order Items</h4>
      <table style="width: 100%; border-collapse: collapse;">
        <thead><tr><th style="padding: 4px 8px; text-align: left;">Item</th><th style="padding: 4px 8px; text-align: right;">Qty</th><th style="padding: 4px 8px; text-align: right;">Price</th></tr></thead>
        <tbody>${row.items.map((item) => `<tr><td style="padding: 4px 8px;">${item.name}</td><td style="padding: 4px 8px; text-align: right;">${item.qty}</td><td style="padding: 4px 8px; text-align: right;">$${item.price.toFixed(2)}</td></tr>`).join('')}</tbody>
      </table>`;
    return div;
  };

  const grid = queryGrid('tbw-grid', container)!;
  const orderData = generateOrderData(100);

  function rebuild(opts: Record<string, unknown>) {
    const heightVal = opts.detailHeight as string ?? 'auto';
    grid.gridConfig = {
      columns,
      features: {
        masterDetail: {
          animation: (opts.animation as string) ?? 'slide',
          detailHeight: heightVal === 'auto' ? 'auto' : Number(heightVal),
          expandOnRowClick: opts.expandOnRowClick as boolean ?? false,
          detailRenderer,
        } as any,
      },
    };
    grid.rows = orderData;
  }

  rebuild({ animation: 'slide', expandOnRowClick: false, detailHeight: 'auto' });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues);
  }) as EventListener);
}
```

## Configuration Options

See [`MasterDetailConfig`](./interfaces/masterdetailconfig/) for the full list of options and their defaults.

### Animation Options

The `animation` option controls how detail rows appear/disappear:

```ts
// Slide animation (default)
features: { masterDetail: { animation: 'slide', ... } }

// Fade animation
features: { masterDetail: { animation: 'fade', ... } }

// No animation
features: { masterDetail: { animation: false, ... } }
```

:::note
Animation respects the grid-level `animation.mode` setting. If the grid has `animation: { mode: 'off' }`, plugin animations are disabled.
:::

## Server-Side Data

> **Requires:** `ServerSidePlugin` — [see Server-Side Plugin](/grid/plugins/server-side.md)

When `ServerSidePlugin` is loaded, master rows are lazily loaded via virtual scrolling (infinite scroll) or pagination — the same way flat data, Tree, or Row Grouping work. MasterDetail does not claim root data, so master rows flow through ServerSide's block cache unchanged.

Detail data can be fetched on demand or embedded in the master row:
- **Async detail data**: On detail expand, MasterDetailPlugin queries `datasource:fetch-children`. ServerSide calls `getChildRows()` and delivers the result.
- **Embedded detail data**: If detail data is already in the master row object (e.g. `row.items`), `detailRenderer` accesses it directly — no `getChildRows()` needed.

When ServerSide is not present, `detailRenderer` works synchronously from the row object.

```ts
import '@toolbox-web/grid/features/master-detail';
import '@toolbox-web/grid/features/server-side';
import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'orderId', header: 'Order ID' },
    { field: 'customer', header: 'Customer' },
    { field: 'total', header: 'Total', type: 'currency' },
  ],
  features: {
    serverSide: {
      pageSize: 50,
      dataSource: {
        async getRows(params) {
          const res = await fetch(`/api/orders?start=${params.startNode}&end=${params.endNode}`);
          const data = await res.json();
          return { rows: data.orders, totalNodeCount: data.total };
        },
        async getChildRows(params) {
          const { row } = params.context;
          const res = await fetch(`/api/orders/${row.id}/items`);
          return { rows: await res.json() };
        },
      },
    },
    masterDetail: {
      detailRenderer: (row, rowIndex) => {
        const plugin = grid.getPluginByName('masterDetail');

        if (plugin.isDetailLoading(rowIndex)) {
          return '<div class="loading">Loading order items…</div>';
        }

        const items = plugin.getDetailData(rowIndex);
        if (!items) {
          return '<div class="loading">Loading…</div>';
        }

        return `
          <div class="order-details">
            <h4>Order Items</h4>
            <ul>
              ${items.map((item: any) => `<li>${item.name} — $${item.price}</li>`).join('')}
            </ul>
          </div>
        `;
      },
    },
  },
};
```

**Data flow:**
1. ServerSide fetches master rows in blocks (virtual scroll or pagination) → renders normally (MasterDetail does not claim root data)
2. User scrolls → ServerSide loads more master rows on demand
3. On detail expand → MasterDetailPlugin queries `datasource:fetch-children` with `{ source: 'master-detail', row, rowIndex }`
4. ServerSide calls `getChildRows()` → broadcasts `datasource:children`
5. MasterDetailPlugin stores the data and re-renders the detail panel
6. `detailRenderer` uses `getDetailData(rowIndex)` to access the async data

**Async API:**
```ts
const plugin = grid.getPluginByName('masterDetail');
plugin.getDetailData(rowIndex);     // Get fetched detail data (or undefined if not loaded)
plugin.isDetailLoading(rowIndex);   // Check if detail data is currently loading
```

:::note
Child rows are fetched as a single batch — no pagination. If a detail row has many children, limit the response server-side.
:::

## Nested Grid Example

```ts
features: {
  masterDetail: {
    detailRenderer: (row) => {
      const childGrid = document.createElement('tbw-grid');
      childGrid.style.height = '200px';
      childGrid.gridConfig = { columns: [...] };
      childGrid.rows = row.items || [];
      return childGrid;
    },
  },
},
```

## Programmatic API

See [`MasterDetailPlugin`](./classes/masterdetailplugin/) for the full list of methods.

```ts
const plugin = grid.getPluginByName('masterDetail');

plugin.expand(rowIndex);
plugin.collapse(rowIndex);
plugin.toggle(rowIndex);
plugin.expandAll();
plugin.collapseAll();
plugin.isExpanded(rowIndex); // boolean
```

## Styling

The master-detail plugin supports CSS custom properties for theming. Override these on `tbw-grid` or a parent container:

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-master-detail-bg` | `var(--tbw-color-row-alt)` | Detail row background |
| `--tbw-master-detail-border` | `var(--tbw-color-border)` | Detail row border |
| `--tbw-detail-padding` | `1em` | Detail content padding |
| `--tbw-detail-max-height` | `31.25rem` (~500px) | Max height for animation |
| `--tbw-animation-duration` | `200ms` | Expand/collapse animation |
| `--tbw-animation-easing` | `ease-out` | Animation curve |

### Example

```css
tbw-grid {
  /* Custom master-detail styling */
  --tbw-master-detail-bg: #f8f9fa;
  --tbw-master-detail-border: #dee2e6;
  --tbw-detail-padding: 1.5rem;
  --tbw-animation-duration: 300ms;
}
```

### CSS Classes

The master-detail plugin uses these class names:

| Class | Element |
| --- | --- |
| `.master-detail-expander` | Expander cell container |
| `.master-detail-toggle` | Expand/collapse icon |
| `.master-detail-row` | Detail row container |
| `.master-detail-row.tbw-expanding` | Row during expand animation |
| `.master-detail-row.tbw-collapsing` | Row during collapse animation |
| `.master-detail-cell` | Detail content wrapper |
| `.tbw-row-expanded` | Applied to a master `.data-grid-row` while its detail panel is showing. Use this for theming expanded master rows instead of `[aria-expanded="true"]` (which lives on the toggle button, not the row). |

## Events

| Event           | Detail                                         | Description                          |
| --------------- | ---------------------------------------------- | ------------------------------------ |
| `detail-expand` | `{ rowIndex, row, expanded }`                  | Fired when a detail row is expanded/collapsed |

## See Also

- **[Tree](/grid/plugins/tree.md)** — Hierarchical tree data
- **[Row Grouping](../grouping-rows/)** — Group rows by field values; master-detail toggles appear on data rows within groups
- **[Selection](/grid/plugins/selection.md)** — Row and cell selection

---

# Multi-Sort Plugin

> Sort by multiple columns with shift-click support.

This plugin is not needed if you only want single-column sorting—just set `sortable: true` on the columns. This is built in to the core. Multi-Sort extends that functionality by enabling 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 '@toolbox-web/grid/features/multi-sort';
```

## Basic Usage

Mark columns as `sortable: true` and enable the feature. Users Shift+click to add columns to the sort stack, and regular click to reset to single-column sort.

#### Angular

```typescript
// Feature import - enables the [multiSort] input
import { GridMultiSortDirective } from '@toolbox-web/grid-angular/features/multi-sort';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-sortable-grid',
  imports: [Grid, GridMultiSortDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [multiSort]="{ maxSortColumns: 3 }"
      (sort-change)="onSortChange($event)"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class SortableGridComponent {
  rows = [
    { name: 'Alice', department: 'Engineering', salary: 95000 },
    { name: 'Bob', department: 'Marketing', salary: 75000 },
  ];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name', sortable: true },
    { field: 'department', header: 'Department', sortable: true },
    { field: 'salary', header: 'Salary', type: 'number', sortable: true },
  ];

  onSortChange(e: CustomEvent) {
    console.log('Sort changed:', e.detail.sortModel);
  }
}
```

## Demo

Use the controls to explore different multi-sort configurations: adjust the maximum number of sort levels, toggle priority badges, or apply an initial sort.

```ts
// MultiSortDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/multi-sort';

const container = document.getElementById('multi-sort-default-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice', department: 'Engineering', salary: 95000, joined: '2023-01-15' },
    { id: 2, name: 'Bob', department: 'Marketing', salary: 75000, joined: '2022-06-20' },
    { id: 3, name: 'Carol', department: 'Engineering', salary: 105000, joined: '2021-03-10' },
    { id: 4, name: 'Dan', department: 'Engineering', salary: 85000, joined: '2023-08-05' },
    { id: 5, name: 'Eve', department: 'Marketing', salary: 72000, joined: '2024-01-12' },
    { id: 6, name: 'Frank', department: 'Sales', salary: 82000, joined: '2022-11-30' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number', sortable: true },
    { field: 'name', header: 'Name', sortable: true },
    { field: 'department', header: 'Department', sortable: true },
    { field: 'salary', header: 'Salary', type: 'number', sortable: true },
    { field: 'joined', header: 'Joined', type: 'date', sortable: true },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(maxSortColumns = 3, showSortIndex = true, initialSort = false) {
    grid.gridConfig = {
      columns,
      features: { multiSort: { maxSortColumns, showSortIndex } },
    };
    grid.rows = sampleData;

    if (initialSort) {
      grid.ready().then(() => {
        grid.getPluginByName('multiSort')?.setSortModel([
          { field: 'department', direction: 'asc' },
          { field: 'salary', direction: 'desc' },
        ]);
      });
    }
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    const v = e.detail.allValues;
    rebuild(v.maxSortColumns as number, v.showSortIndex as boolean, v.initialSort as boolean);
  }) as EventListener);
}
```

Hold **Shift** and click column headers to add columns to the sort stack. Set **Max sort columns** to `1` for single-column-only sorting.

## Configuration Options

See [`MultiSortConfig`](./interfaces/multisortconfig/) for the full list of options and their defaults.

## Initial Sort

Use `setSortModel()` to set a pre-configured sort order after the grid initializes:

```ts
const plugin = grid.getPluginByName('multiSort');
plugin.setSortModel([
  { field: 'department', direction: 'asc' },
  { field: 'salary', direction: 'desc' },
]);
```

## Events

The grid fires a `sort-change` event whenever the sort model changes:

```ts
grid.on('sort-change', ({ sortModel }) => {
  console.log('Sort model:', sortModel);
  // [{ field: 'name', direction: 'asc' }, { field: 'salary', direction: 'desc' }]
});
```

## Programmatic API

See [`MultiSortPlugin`](./classes/multisortplugin/) for the full list of methods.

```ts
const plugin = grid.getPluginByName('multiSort');

plugin.setSortModel([{ field: 'department', direction: 'asc' }]);
plugin.getSortModel();               // SortModel[]
plugin.clearSort();
plugin.getSortDirection('salary');    // 'asc' | 'desc' | undefined
plugin.getSortIndex('salary');        // number | undefined
```

## Keyboard Shortcuts

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

## Styling

The grid uses Light DOM, so standard CSS selectors work for styling sort indicators:

```css
/* Sort indicator icon */
tbw-grid .sort-indicator {
  margin-left: 4px;
}

/* Sort priority badge */
tbw-grid .sort-index {
  background: var(--tbw-multi-sort-badge-bg, var(--tbw-color-panel-bg));
  color: var(--tbw-multi-sort-badge-color, var(--tbw-color-fg));
  width: var(--tbw-multi-sort-badge-size, 1em);
  height: var(--tbw-multi-sort-badge-size, 1em);
}
```

## Row Insertion with Active Sort

When multi-sort is active, assigning `rows` automatically re-sorts the data — so a
newly inserted row will jump to its sorted position. If you want the row to stay
exactly where you placed it (e.g., after a user clicks "Add Row"), use `insertRow()`:

```ts
grid.insertRow(3, newRow); // stays at visible index 3, auto-animates
```

The row is also added to source data, so the next full `grid.rows = freshData`
assignment re-sorts normally. See the
[API Reference → Insert & Remove Rows](/grid/api-reference.md#insert--remove-rows)
for full details.

:::tip
Do **not** use `insertRow()` for data refreshes (API responses,
WebSocket updates). In those cases just set `grid.rows = newData` and let
multi-sort re-apply.
:::

## Custom Sort Logic

`MultiSortPlugin` owns the multi-column sort path and **does not consult**
`gridConfig.sortHandler` — that property is only honored by the single-column
sort path used when `MultiSortPlugin` is absent. To customize sort behavior
when multi-sort is enabled, use **`column.sortComparator`** on the columns
that need it. `sortComparator` is honored by every sort code path in the grid
(core, multi-sort, tree, server-side `sortMode: 'local'`).

```ts
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name', sortable: true },
    {
      field: 'salary',
      header: 'Salary',
      type: 'number',
      sortable: true,
      // Custom comparator: pin negative values (debts) to the end regardless of direction
      sortComparator: (a, b) => {
        if (a < 0 && b >= 0) return 1;
        if (b < 0 && a >= 0) return -1;
        return a - b;
      },
    },
  ],
  features: { multiSort: true },
};
```

**Comparator signature:** `(a, b, rowA, rowB) => number` — return `< 0` to put
`a` first, `> 0` for `b`, `0` for equal. Direction (`asc`/`desc`) is applied
automatically by the sort engine.

## Server-Side Sorting

For backends that own sort ordering, use
[`ServerSidePlugin`](../server-side/) — it ships the current `sortModel` (all
columns, in priority order) to your `getRows` handler so the backend can
return rows in the requested order. This is the right pattern for paginated /
infinite-scroll datasets where client-side sort isn't viable.

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

grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name', sortable: true },
    { field: 'salary', header: 'Salary', sortable: true },
  ],
  plugins: [
    new MultiSortPlugin(),
    new ServerSidePlugin({
      dataSource: {
        getRows: async ({ startNode, endNode, sortModel }) => {
          // sortModel: [{ field: 'name', direction: 'asc' }, { field: 'salary', direction: 'desc' }]
          const sortQuery = sortModel
            .map((s) => `${s.field}:${s.direction}`)
            .join(',');
          const response = await fetch(
            `/api/data?from=${startNode}&to=${endNode}&sort=${sortQuery}`,
          );
          const { rows, totalNodeCount } = await response.json();
          return { rows, totalNodeCount };
        },
      },
    }),
  ],
};
```

`sortComparator` is synchronous, so use it only for custom **client-side**
comparisons. If sorting needs to be owned by your backend, use
`ServerSidePlugin`; if you only need custom single-column sort behavior, use
`sortHandler` instead.

## See Also

- **[Filtering](../filtering/)** — Filter rows by column values
- **[Server-Side Data](../server-side/)** — Block-based virtual scrolling for large datasets
- **[Plugins Overview](/grid/plugins.md)** — Plugin compatibility and combinations

---

# Pinned Columns Plugin

> Pin columns to the left or right side of the grid.

The Pinned Columns plugin freezes columns to the left or right edge of the grid—essential for keeping key identifiers or action buttons visible while scrolling through wide datasets. Just set `pinned: 'left'` or `pinned: 'right'` on your column definitions and the plugin handles the rest.

## Installation

```ts
import '@toolbox-web/grid/features/pinned-columns';
```

## Basic Usage

Pin important columns like ID on the left and action buttons on the right. The pinned columns stay fixed while the middle content scrolls horizontally.

#### Angular

```typescript
// Feature import - enables the [pinnedColumns] input
import { GridPinnedColumnsDirective } from '@toolbox-web/grid-angular/features/pinned-columns';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid, GridPinnedColumnsDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [pinnedColumns]="true"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class EmployeeGridComponent {
  rows = [];

  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID', pinned: 'left', width: 80 },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'currency' },
    { field: 'actions', header: 'Actions', pinned: 'right', width: 120 },
  ];
}
```

## Demo

```ts
// PinnedColumnsDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/pinned-columns';

const container = document.getElementById('pinned-columns-default-demo');
if (container) {
  const FIRST_NAMES = ['Alice', 'Bob', 'Carol', 'Dan', 'Eve', 'Frank', 'Grace', 'Henry', 'Ivy', 'Jack'];
  const LAST_NAMES = ['Johnson', 'Smith', 'Williams', 'Brown', 'Jones', 'Davis', 'Miller', 'Wilson', 'Moore', 'Taylor'];
  const DEPARTMENTS = ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance', 'Legal', 'Support', 'Design'];
  const CITIES = ['New York', 'Los Angeles', 'Chicago', 'Houston', 'Phoenix', 'Philadelphia', 'San Antonio', 'Dallas'];
  const COUNTRIES = ['USA', 'Canada', 'UK', 'Germany', 'France', 'Australia', 'Japan', 'Brazil'];

  function generateRows(count: number) {
    const rows = [];
    for (let i = 0; i < count; i++) {
      const first = FIRST_NAMES[i % FIRST_NAMES.length];
      const last = LAST_NAMES[Math.floor(i / FIRST_NAMES.length) % LAST_NAMES.length];
      rows.push({
        id: i + 1,
        name: `${first} ${last}`,
        email: `${first.toLowerCase()}.${last.toLowerCase()}@example.com`,
        department: DEPARTMENTS[i % DEPARTMENTS.length],
        phone: `+1-555-${String(i).padStart(4, '0')}`,
        address: `${100 + i} ${['Main', 'Oak', 'Pine', 'Elm', 'Maple'][i % 5]} St`,
        city: CITIES[i % CITIES.length],
        country: COUNTRIES[i % COUNTRIES.length],
        actions: '...',
      });
    }
    return rows;
  }

  function toPinned(value: string) {
    return value === 'none' ? undefined : value;
  }

  const sampleData = generateRows(1000);
  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(pins: Record<string, string>) {
    grid.gridConfig = {
      columns: [
        { field: 'id', header: 'ID', type: 'number', width: 60, pinned: toPinned(pins.pinId ?? 'left') },
        { field: 'name', header: 'Name', width: 150, pinned: toPinned(pins.pinName ?? 'left') },
        { field: 'email', header: 'Email', width: 220, pinned: toPinned(pins.pinEmail ?? 'none') },
        { field: 'department', header: 'Department', width: 150, pinned: toPinned(pins.pinDepartment ?? 'none') },
        { field: 'phone', header: 'Phone', width: 150, pinned: toPinned(pins.pinPhone ?? 'none') },
        { field: 'address', header: 'Address', width: 250, pinned: toPinned(pins.pinAddress ?? 'none') },
        { field: 'city', header: 'City', width: 120, pinned: toPinned(pins.pinCity ?? 'none') },
        { field: 'country', header: 'Country', width: 120, pinned: toPinned(pins.pinCountry ?? 'none') },
        { field: 'actions', header: 'Actions', width: 100, pinned: toPinned(pins.pinActions ?? 'right') },
      ],
      fitMode: 'fixed',
      features: { pinnedColumns: true },
    };
    grid.rows = sampleData;
  }

  rebuild({});

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues as Record<string, string>);
  }) as EventListener);
}
```

Use the controls below to change which columns are pinned to the left, right, or not pinned.
Pinned columns are automatically reordered to the grid edges—left-pinned columns move to the
start, right-pinned columns move to the end. Unpinning restores the column to its original position.

## Configuration Options

The plugin has no configuration options. It is activated when columns have `pinned: 'left'` or `pinned: 'right'` set.

## Programmatic API

See [`PinnedColumnsPlugin`](./classes/pinnedcolumnsplugin/) for the full list of methods.

```ts
const plugin = grid.getPluginByName('pinnedColumns');

// Get currently pinned columns
const leftPinned = plugin.getLeftPinnedColumns();
const rightPinned = plugin.getRightPinnedColumns();

// Clear all sticky positions
plugin.clearStickyPositions();

// Recalculate offsets (e.g., after column resize)
plugin.refreshStickyOffsets();
```

:::note
To pin or unpin columns at runtime, update the column's `pinned` property in your `gridConfig.columns` and re-assign the config. The plugin reads `pinned` from column definitions during each render cycle.
:::

### RTL Support

For direction-independent pinning, use logical values `'start'` and `'end'` instead of `'left'`/`'right'`:

```ts
{ field: 'id', pinned: 'start' }  // Left in LTR, Right in RTL
{ field: 'actions', pinned: 'end' } // Right in LTR, Left in RTL
```

## Column Reordering Behaviour

When a column is pinned (either via config or the context menu), the plugin **automatically
reorders** it to the appropriate edge of the grid:

- `pinned: 'left'` → moved to the leftmost position (after other left-pinned columns)
- `pinned: 'right'` → moved to the rightmost position (before other right-pinned columns)

When a column is unpinned via the context menu, it is restored to its **original position**
in the column order.

This ensures pinned columns are always visible at the grid edges without requiring the user
to scroll.

## Known Limitations

- **Column Groups support**: Pinned columns work with the
  [Column Groups plugin](../grouping-columns/). When a pinned column belongs to a
  column group, the group header is automatically split so the pinned portion stays
  sticky while the rest scrolls normally. For explicit (named) groups, the group label
  scrolls with the non-pinned fragment until it reaches the pinned edge, then transfers
  to the pinned fragment for a seamless experience.

- **Header-only sticky in virtualized grids**: Due to the row virtualization architecture
  (`will-change: transform` on the rows container), `position: sticky` only works on
  **header cells**. Data row cells receive the sticky CSS classes but the browser cannot
  honour them because the transformed ancestor creates a new containing block.

## See Also

- **[Pinned Rows](/grid/plugins/pinned-rows.md)** — Pin rows to top/bottom
- **[Column Reorder](../reorder-columns/)** — Drag-to-reorder columns
- **[Column Groups](../grouping-columns/)** — Group column headers

---

# Pinned Rows (Status Bar) Plugin

> Pin summary or custom rows to the top or bottom of the grid.

The Pinned Rows plugin creates a fixed status bar 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 '@toolbox-web/grid/features/pinned-rows';
```

## Basic Usage

Pinned rows are configured with a unified `slots[]` array. Each slot becomes
its own DOM row at `position: 'top'` or `position: 'bottom'` (default
`'bottom'`), in declared order. A slot is either an **aggregation row**
(sum/avg/min/max/count/first/last or a custom function per column) or a
**panel row** (a `render` function — built-in or custom).

#### Angular

```typescript
// Feature import - enables the [pinnedRows] input
import { GridPinnedRowsDirective } from '@toolbox-web/grid-angular/features/pinned-rows';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';
import { rowCountPanel } from '@toolbox-web/grid/plugins/pinned-rows';

@Component({
  selector: 'app-order-grid',
  imports: [Grid, GridPinnedRowsDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [pinnedRows]="pinnedRowsConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class OrderGridComponent {
  rows = [];

  columns: ColumnConfig[] = [
    { field: 'product', header: 'Product' },
    { field: 'quantity', header: 'Qty', type: 'number' },
    { field: 'price', header: 'Price', type: 'currency' },
  ];

  pinnedRowsConfig = {
    slots: [
      {
        id: 'totals',
        position: 'bottom' as const,
        aggregators: { quantity: 'sum', price: 'sum' },
        cells: { product: 'Totals:' },
      },
      { id: 'count', position: 'bottom' as const, render: rowCountPanel() },
    ],
  };
}
```

## Demo

Use the controls to explore aggregation rows (top or bottom, single or
stacked, full-width or per-column), the built-in row-count status panel
and a custom right-zone panel. Every behaviour below is driven by the
same `slots[]` array.

```ts
// PinnedRowsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/pinned-rows';
import {
rowCountPanel,
type PinnedRowSlot,
type ZonedPanelRender,
} from '@toolbox-web/grid/plugins/pinned-rows';

const container = document.getElementById('pinned-rows-demo');
if (container) {
  const names = ['Widget', 'Gadget', 'Gizmo', 'Doohickey', 'Thingamabob'];
  const data = Array.from({ length: 100 }, (_, i) => ({
    id: i + 1,
    name: names[i % names.length],
    quantity: Math.floor(Math.random() * 100) + 10,
    price: Math.round((Math.random() * 50 + 5) * 100) / 100,
  }));

  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'quantity', header: 'Qty', type: 'number' },
    { field: 'price', header: 'Price', type: 'number' },
  ];

  const formatCurrency = (value: unknown) => `$${(value as number).toFixed(2)}`;
  const grid = queryGrid('tbw-grid', container)!;

  function build(opts: {
    aggPosition: 'top' | 'bottom';
    multipleRows: boolean;
    fullWidth: boolean;
    showRowCount: boolean;
    showCustom: boolean;
  }) {
    const aggregationSlots: PinnedRowSlot[] = opts.multipleRows
      ? [
          {
            id: 'sum',
            position: opts.aggPosition,
            label: 'Sum',
            aggregators: { quantity: 'sum', price: { aggFunc: 'sum', formatter: formatCurrency } },
            cells: { id: 'Sum:', name: '' },
          },
          {
            id: 'avg',
            position: opts.aggPosition,
            label: 'Average',
            aggregators: {
              quantity: { aggFunc: 'avg', formatter: (v: unknown) => (v as number).toFixed(1) },
              price: { aggFunc: 'avg', formatter: formatCurrency },
            },
            cells: { id: 'Avg:', name: '' },
          },
          {
            id: 'minmax',
            position: opts.aggPosition,
            label: 'Min/Max',
            aggregators: { quantity: 'min', price: { aggFunc: 'max', formatter: formatCurrency } },
            cells: { id: 'Min/Max:', name: '' },
          },
        ]
      : [
          {
            id: 'totals',
            position: opts.aggPosition,
            label: 'Totals',
            aggregators: {
              name: (rows: unknown[]) =>
                `${new Set((rows as { name: string }[]).map((r) => r.name)).size} unique`,
              quantity: 'sum',
              price: { aggFunc: 'sum', formatter: formatCurrency },
            },
            cells: { id: 'Totals:' },
          },
        ];

    // All status panels share a SINGLE slot so they appear on one DOM row.
    // Each entry in `render: [...]` is a zone contribution within that row;
    // adding more slots would stack additional rows below.
    const statusContribs: ZonedPanelRender[] = [];
    if (opts.showRowCount) statusContribs.push({ zone: 'left', render: rowCountPanel() });
    if (opts.showCustom) {
      statusContribs.push({
        zone: 'right',
        render: (ctx) => {
          const rows = ctx.rows as Array<{ quantity: number; price: number }>;
          const total = rows.reduce(
            (sum, row) => sum + (row.quantity || 0) * (row.price || 0),
            0,
          );
          const el = document.createElement('strong');
          el.className = 'tbw-status-panel';
          el.textContent = `Inventory value: ${formatCurrency(total)}`;
          return el;
        },
      });
    }

    const slots: PinnedRowSlot[] = [...aggregationSlots];
    if (statusContribs.length > 0) {
      slots.push({ id: 'status', position: 'bottom', render: statusContribs });
    }

    grid.gridConfig = {
      columns,
      features: {
        pinnedRows: { fullWidth: opts.fullWidth, slots },
      },
    };
    grid.rows = data;
  }

  build({
    aggPosition: 'bottom',
    multipleRows: false,
    fullWidth: false,
    showRowCount: true,
    showCustom: true,
  });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    const v = e.detail.allValues;
    build({
      aggPosition: v.aggPosition as 'top' | 'bottom',
      multipleRows: v.multipleRows as boolean,
      fullWidth: v.fullWidth as boolean,
      showRowCount: v.showRowCount as boolean,
      showCustom: v.showCustom as boolean,
    });
  }) as EventListener);
}
```

## Configuration Options

| Option      | Type                | Default    | Description                                                                  |
| ----------- | ------------------- | ---------- | ---------------------------------------------------------------------------- |
| `slots`     | `PinnedRowSlot[]`   | `[]`       | Unified ordered list of pinned-row slots (see [Slots API](#slots-api))       |
| `fullWidth` | `boolean`           | `false`    | Default `fullWidth` mode applied to every aggregation slot                   |

> **Legacy fields** — `position`, `showRowCount`, `showSelectedCount`,
> `showFilteredCount`, `aggregationRows`, `customPanels` — are still accepted
> for backwards compatibility but are deprecated and ignored when `slots` is
> set. They will be removed in a future major release. New code should use
> `slots`. See the [migration notes](#migrating-from-legacy-fields) below.

## Slots API

The `slots[]` array is a unified, ordered list of pinned-row entries. Each
slot becomes its own DOM row inside its `position` area (`'top'` or
`'bottom'`, default `'bottom'`), in declared order. Two slot shapes coexist:

- **Aggregation slot** — anything **without** a `render` field is treated as
  an aggregation row (same shape as `AggregationRowConfig`: `aggregators`,
  `cells`, `label`, `fullWidth`).
- **Panel slot** — anything **with** a `render` field. `render` is either a
  `(ctx) => HTMLElement | null` function (rendered into the left zone), or
  an array of `{ zone?: 'left' | 'center' | 'right', render }` entries.

A panel render that returns `null` skips that contribution; a slot whose
renderers all return `null` is dropped from the DOM. This is how the built-in
`selectedCountPanel` and `filteredCountPanel` self-hide when their count is
zero / unfiltered.

### Built-in panel renderers

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

| Renderer                | Always renders?                         |
| ----------------------- | --------------------------------------- |
| `rowCountPanel()`       | Yes                                     |
| `selectedCountPanel()`  | Only when `selectedRows > 0`            |
| `filteredCountPanel()`  | Only when `filteredRows !== totalRows`  |

### Example

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

features: {
  pinnedRows: {
    slots: [
      // Aggregation row at the top
      { position: 'top', aggregators: { price: 'sum' }, cells: { id: 'Totals:' } },

      // Three stacked status-panel rows at the bottom (in this order)
      { position: 'bottom', render: rowCountPanel() },
      { position: 'bottom', render: filteredCountPanel() },
      { position: 'bottom', render: selectedCountPanel() },

      // Mixed-zone panel: left + right content in one row
      {
        position: 'bottom',
        render: [
          { zone: 'left',  render: (ctx) => myLeftBadge(ctx) },
          { zone: 'right', render: (ctx) => myRightBadge(ctx) },
        ],
      },
    ],
  },
},
```

### Framework adapters

All three adapters bridge `slots[].render` automatically — return your
framework's native node and the adapter wraps it in a vanilla DOM element
via the existing portal/teleport/component-rendering machinery:

| Adapter | `render` may return                        |
| ------- | ------------------------------------------ |
| React   | `ReactNode \| null` (e.g. `<span>...</span>`) |
| Vue     | `VNode \| null` (e.g. `h('span', ...)`)    |
| Angular | `Type<unknown> \| null` (a component class) |

The adapter feature modules cache the host DOM element per-renderer across
calls, so the plugin's reference-equality short-circuit keeps the pinned
row stable across grid refreshes (no React/Vue unmount-remount loop, no
Angular component re-creation). You can therefore write the renderers as
plain inline functions — no need for manual `useRef` / `ref` host caching:

#### Angular

```ts
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import { GridPinnedRowsDirective } from '@toolbox-web/grid-angular/features/pinned-rows';
import { LegendComponent } from './legend.component';

@Component({
  selector: 'app-grid',
  imports: [Grid, GridPinnedRowsDirective],
  template: `<tbw-grid [rows]="rows" [pinnedRows]="pinnedRows" />`,
})
export class AppGrid {
  rows = [];
  pinnedRows = {
    slots: [
      { id: 'legend', position: 'bottom' as const, render: LegendComponent },
    ],
  };
}
```

## Aggregation Rows

An **aggregation slot** (any slot without a `render` field) computes values
from the current rows on a per-column basis:

```ts
features: {
  pinnedRows: {
    slots: [
      {
        id: 'totals',
        position: 'bottom',
        aggregators: {
          // Simple string aggregator
          quantity: 'sum',
          // Object syntax with formatter
          price: {
            aggFunc: 'sum',
            formatter: (value) => `$${value.toFixed(2)}`,
          },
        },
        cells: { id: 'Totals:', name: '' },
      },
    ],
  },
},
```

### Aggregator Syntax

| Syntax   | Example                                              | Description                |
| -------- | ---------------------------------------------------- | -------------------------- |
| String   | `'sum'`                                              | Built-in aggregator        |
| Function | `(rows, field) => rows.length`                       | Custom aggregator function |
| Object   | `{ aggFunc: 'sum', formatter: (v) => v.toFixed(2) }` | Aggregator with formatter  |

### Built-in Aggregators

`sum`, `avg`, `count`, `min`, `max`, `first`, `last`

## Full-Width Mode

When `fullWidth` is `true`, an aggregation slot renders as a single spanning
cell with the label and aggregated values displayed inline—similar to the
row grouping plugin's full-width mode. When `false` (the default), each
column gets its own cell aligned to the grid template.

The `label` property works in both modes. In per-column mode it renders as
an overlay at the left edge of the row, independent of column width—so the
text won't truncate even if the first column is narrow.

Set `fullWidth` globally on the plugin config or per-slot on the aggregation
slot. Per-slot settings override the global default:

```ts
features: {
  pinnedRows: {
    fullWidth: true,  // All aggregation slots span full width by default
    slots: [
      {
        id: 'totals',
        label: 'Totals',
        aggregators: { quantity: 'sum', price: 'sum' },
      },
      {
        id: 'detail',
        fullWidth: false,  // Override: render per-column
        aggregators: { quantity: 'avg', price: 'avg' },
        cells: { product: 'Averages:' },
      },
    ],
  },
},
```

## Custom Panel Slots

Use a panel slot — any slot with a `render` field — to inject custom
content. `render` is either a single function (rendered into the left zone)
or an array of `{ zone, render }` entries to populate `'left'`, `'center'`,
and/or `'right'` zones in one row:

```ts
features: {
  pinnedRows: {
    slots: [
      {
        id: 'info',
        position: 'bottom',
        render: [
          {
            zone: 'right',
            render: (ctx) => {
              const el = document.createElement('span');
              el.textContent = `Rows: ${ctx.totalRows}`;
              return el;
            },
          },
        ],
      },
    ],
  },
},
```

Return `null` from a render function to skip that contribution; if every
contribution in a slot returns `null` the whole row is dropped. The built-in
`selectedCountPanel()` and `filteredCountPanel()` use this to self-hide.

### Stateful counter — combine totals, filter and selection

Because everything you need is on the context object, a single render
function can adapt its message to grid state without reading from any
plugin directly. The example below shows one combined counter that:

- shows `Total: N rows` when nothing is filtered or selected,
- switches to `Filtered: M / N` when a filter is active,
- switches to `Selected: S of N` when rows are selected,
- and combines into `Selected: S of M / N` when both apply.

```ts
features: {
  pinnedRows: {
    slots: [
      {
        id: 'counter',
        position: 'bottom',
        render: (ctx) => {
          const { totalRows, filteredRows, selectedRows } = ctx;
          const isFiltered = filteredRows !== totalRows;
          const visible = isFiltered ? `${filteredRows} / ${totalRows}` : `${totalRows}`;

          let text: string;
          if (selectedRows > 0) {
            text = `Selected: ${selectedRows} of ${visible}`;
          } else if (isFiltered) {
            text = `Filtered: ${visible}`;
          } else {
            text = `Total: ${totalRows} rows`;
          }

          const el = document.createElement('span');
          el.className = 'tbw-status-panel';
          el.textContent = text;
          return el;
        },
      },
    ],
  },
},
```

## Migrating from Legacy Fields

The legacy top-level fields are deprecated. Map them to `slots` as follows:

| Legacy field                    | Slots equivalent                                                         |
| ------------------------------- | ------------------------------------------------------------------------ |
| `position: 'top' \| 'bottom'`   | Per-slot `position` field                                                |
| `showRowCount: true`            | `{ render: rowCountPanel() }`                                            |
| `showSelectedCount: true`       | `{ render: selectedCountPanel() }`                                       |
| `showFilteredCount: true`       | `{ render: filteredCountPanel() }`                                       |
| `aggregationRows: [{ ... }]`    | Same shape — drop into `slots[]` (no `render` field)                     |
| `customPanels: [{ render }]`    | Wrap as `{ render: [{ zone: panel.position, render: panel.render }] }`   |

## See Also

- **[Pinned Columns](/grid/plugins/pinned-columns.md)** — Sticky columns
- **[Core Configuration](/grid/core.md)** — Grid configuration overview

---

# Pivot Table Plugin

> Transform row data into a cross-tabulation (pivot table) layout.

The Pivot plugin transforms flat data into a pivot table view.

## Installation

```ts
import '@toolbox-web/grid/features/pivot';
```

## Basic Usage

#### Angular

```typescript
// Feature import - enables the [pivot] input
import { GridPivotDirective } from '@toolbox-web/grid-angular/features/pivot';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-sales-pivot',
  imports: [Grid, GridPivotDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [pivot]="pivotConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class SalesPivotComponent {
  rows = [...]; // Your sales data

  columns: ColumnConfig[] = [
    { field: 'region', header: 'Region' },
    { field: 'product', header: 'Product' },
    { field: 'quarter', header: 'Quarter' },
    { field: 'sales', header: 'Sales', type: 'number' },
  ];

  pivotConfig = {
    rowGroupFields: ['region', 'product'],
    columnGroupFields: ['quarter'],
    valueFields: [{ field: 'sales', aggFunc: 'sum', header: 'Total' }],
  };
}
```

## Demo

```ts
// PivotDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/pivot';

const container = document.getElementById('pivot-default-demo');
if (container) {
  const salesData = [
    { region: 'North', product: 'Widget A', quarter: 'Q1', sales: 1200 },
    { region: 'North', product: 'Widget B', quarter: 'Q1', sales: 800 },
    { region: 'North', product: 'Widget A', quarter: 'Q2', sales: 1500 },
    { region: 'North', product: 'Widget B', quarter: 'Q2', sales: 950 },
    { region: 'South', product: 'Widget A', quarter: 'Q1', sales: 900 },
    { region: 'South', product: 'Widget B', quarter: 'Q1', sales: 1100 },
    { region: 'South', product: 'Widget A', quarter: 'Q2', sales: 1300 },
    { region: 'South', product: 'Widget B', quarter: 'Q2', sales: 1400 },
    { region: 'East', product: 'Widget A', quarter: 'Q1', sales: 750 },
    { region: 'East', product: 'Widget B', quarter: 'Q1', sales: 650 },
    { region: 'East', product: 'Widget A', quarter: 'Q2', sales: 880 },
    { region: 'East', product: 'Widget B', quarter: 'Q2', sales: 720 },
  ];
  const columns = [
    { field: 'region', header: 'Region' },
    { field: 'product', header: 'Product' },
    { field: 'quarter', header: 'Quarter' },
    { field: 'sales', header: 'Sales', type: 'number' },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(opts: Record<string, unknown>) {
    const aggFunc = (opts.aggFunc as string) ?? 'sum';
    const headerLabel = aggFunc === 'sum' ? 'Total Sales'
      : aggFunc === 'avg' ? 'Avg Sales'
      : aggFunc === 'count' ? 'Count'
      : aggFunc === 'min' ? 'Min Sales'
      : 'Max Sales';
    const animRaw = (opts.animation as string) ?? 'slide';
    const animation = animRaw === 'false' ? false : animRaw;
    const valueField: Record<string, unknown> = {
      field: 'sales', aggFunc, header: headerLabel,
      format: (v: number) => `$${v.toLocaleString()}`,
    };
    const pivotConfig: Record<string, unknown> = {
      active: opts.active as boolean ?? true,
      animation,
      rowGroupFields: ['region', 'product'],
      columnGroupFields: ['quarter'],
      valueFields: [valueField],
      showTotals: opts.showTotals as boolean ?? true,
      showGrandTotal: opts.showGrandTotal as boolean ?? true,
      showToolPanel: opts.showToolPanel as boolean ?? true,
      defaultExpanded: opts.defaultExpanded as boolean ?? true,
      indentWidth: opts.indentWidth as number ?? 20,
    };
    grid.gridConfig = {
      columns,
      features: { pivot: pivotConfig as any },
    };
    grid.rows = salesData;
  }

  rebuild({ active: true, showTotals: true, showGrandTotal: true, showToolPanel: true, defaultExpanded: true, indentWidth: 20, animation: 'slide', aggFunc: 'sum' });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues);
  }) as EventListener);
}
```

Use the controls to explore the full pivot configuration — toggle active state, totals, grand total, tool panel, default expansion, indent width, aggregation function, and animation style. For sorting, see the [Sorting](#sorting) section below.

## Events & Programmatic API

```ts
// PivotEventsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/pivot';

const container = document.getElementById('pivot-events-demo');
if (container) {
  const salesData = [
    { region: 'North', product: 'Widget A', quarter: 'Q1', sales: 1200 },
    { region: 'North', product: 'Widget B', quarter: 'Q1', sales: 800 },
    { region: 'North', product: 'Widget A', quarter: 'Q2', sales: 1500 },
    { region: 'North', product: 'Widget B', quarter: 'Q2', sales: 950 },
    { region: 'South', product: 'Widget A', quarter: 'Q1', sales: 900 },
    { region: 'South', product: 'Widget B', quarter: 'Q1', sales: 1100 },
    { region: 'South', product: 'Widget A', quarter: 'Q2', sales: 1300 },
    { region: 'South', product: 'Widget B', quarter: 'Q2', sales: 1400 },
    { region: 'East', product: 'Widget A', quarter: 'Q1', sales: 750 },
    { region: 'East', product: 'Widget B', quarter: 'Q1', sales: 650 },
    { region: 'East', product: 'Widget A', quarter: 'Q2', sales: 880 },
    { region: 'East', product: 'Widget B', quarter: 'Q2', sales: 720 },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  grid.gridConfig = {
    columns: [
      { field: 'region', header: 'Region' },
      { field: 'product', header: 'Product' },
      { field: 'quarter', header: 'Quarter' },
      { field: 'sales', header: 'Sales', type: 'number' },
    ],
    features: {
      pivot: {
        rowGroupFields: ['region', 'product'],
        columnGroupFields: ['quarter'],
        valueFields: [{ field: 'sales', aggFunc: 'sum', header: 'Total Sales' }],
        showTotals: true,
        showGrandTotal: true,
        showToolPanel: true,
        defaultExpanded: true,
      } as any,
    },
  };
  grid.rows = salesData;

  // Event log
  const entries = document.getElementById('pivot-event-entries')!;
  const MAX_LOG = 20;

  function log(type: string, detail: string) {
    const el = document.createElement('div');
    el.className = 'pivot-event-entry';
    el.innerHTML = `<span class="pivot-event-type">${type}</span> ${detail}`;
    entries.prepend(el);
    while (entries.children.length > MAX_LOG) {
      entries.lastElementChild?.remove();
    }
  }

  grid.addEventListener('pivot-toggle', ((e: CustomEvent) => {
    const d = e.detail;
    log('toggle', `<strong>${d.label}</strong> ${d.expanded ? 'expanded' : 'collapsed'} (depth ${d.depth})`);
  }) as EventListener);

  grid.addEventListener('pivot-state-change', ((e: CustomEvent) => {
    log('state', `Pivot is now <strong>${e.detail.active ? 'active' : 'inactive'}</strong>`);
  }) as EventListener);

  grid.addEventListener('pivot-config-change', ((e: CustomEvent) => {
    const d = e.detail;
    const parts = [`property: <strong>${d.property}</strong>`];
    if (d.field) parts.push(`field: ${d.field}`);
    if (d.zone) parts.push(`zone: ${d.zone}`);
    log('config', parts.join(', '));
  }) as EventListener);

  // Programmatic API buttons
  const plugin = grid.getPluginByName('pivot') as any;

  document.getElementById('pivot-expand-all')?.addEventListener('click', () => {
    plugin?.expandAll();
    log('api', 'Called <strong>expandAll()</strong>');
  });

  document.getElementById('pivot-collapse-all')?.addEventListener('click', () => {
    plugin?.collapseAll();
    log('api', 'Called <strong>collapseAll()</strong>');
  });

  document.getElementById('pivot-get-expanded')?.addEventListener('click', () => {
    const groups = plugin?.getExpandedGroups() ?? [];
    log('api', `<strong>getExpandedGroups()</strong> → [${groups.map((k: string) => `"${k}"`).join(', ')}]`);
  });
}
```

Click groups to expand/collapse and watch the event log. Use the buttons to call the programmatic API. Open the tool panel and drag fields between zones to see `pivot-config-change` events.

## Configuration Options

See [`PivotConfig`](./Interfaces/PivotConfig/) for the full list of options and defaults.

Key options:

- **`showTotals`** — Shows/hides the per-row **Total column** on the right (the sum across all pivot columns for each row). This does *not* affect the aggregated values shown in group rows.
- **`showGrandTotal`** — Shows/hides the grand total row at the bottom.
- **`grandTotalInRowModel`** — When `true`, the grand total renders as a regular row instead of a sticky footer (useful for data export and copy/paste).

## Aggregation Functions

Built-in: `sum`, `avg`, `count`, `min`, `max`, `first`, `last`

### Custom Aggregators

You can provide a custom aggregation function instead of a built-in name:

```ts
features: {
  pivot: {
    rowGroupFields: ['region'],
    valueFields: [{
      field: 'sales',
      aggFunc: (values) => values.reduce((a, b) => a + b * 2, 0),
    }],
  },
}
```

Custom aggregators appear as "CUSTOM" in the tool panel and cannot be changed via the UI.

## Value Formatting

Format aggregated values with a `format` function on the value field:

```ts
valueFields: [{
  field: 'revenue',
  aggFunc: 'sum',
  format: (value) => `$${value.toLocaleString()}`,
}]
```

If no `format` is provided, the plugin falls back to the original column's `format` function.

## Programmatic-Only Usage

To use pivot transformation without exposing the tool panel UI to users:

```ts
features: {
  pivot: {
    showToolPanel: false,
    rowGroupFields: ['region'],
    columnGroupFields: ['quarter'],
    valueFields: [{ field: 'sales', aggFunc: 'sum' }],
  },
},
```

The pivot API methods remain available for programmatic control.

## Tool Panel

When `showToolPanel: true` (default), the pivot panel lets users configure the pivot interactively:

- **Drag fields** between Row Groups, Column Groups, and Values zones
- **Reorder fields** within a zone by dragging
- **Search fields** using the filter input at the top of the Available Fields list
- **Change aggregation** via the dropdown on each value field (built-in functions only — custom aggregators show "CUSTOM" and cannot be changed via the UI)

The panel fires `pivot-config-change` events when users modify the configuration.

## Animation

The plugin supports animated expand/collapse transitions. Animation respects the grid-level
`animation.mode` setting and can be customized per-plugin:

```ts
features: {
  pivot: {
    rowGroupFields: ['region'],
    valueFields: [{ field: 'sales', aggFunc: 'sum' }],
    animation: 'slide', // 'slide' | 'fade' | false
  },
},
```

Animation is automatically disabled when `animation.mode` is `'off'` or when the user prefers
reduced motion (`'reduced-motion'` mode with system preference).

## Programmatic API

```ts
const plugin = grid.getPluginByName('pivot');

plugin.expand('North__Widget A');  // expand a specific group by key
plugin.collapse('North');           // collapse a group
plugin.expandAll();
plugin.collapseAll();
plugin.getExpandedGroups();         // returns string[] of expanded keys
```

## Sorting

Pivot columns support interactive sorting — click any column header to cycle through ascending, descending, and unsorted.

### Multi-Column Sort

When the [Multi-Sort plugin](/grid/plugins/multi-sort.md) is loaded alongside Pivot, shift-click adds
secondary sort columns with numbered priority badges. Pivot translates the multi-sort model into
hierarchical sorting that respects the group structure.

### Programmatic Sort

You can also configure sorting programmatically:

```ts
features: {
  pivot: {
    rowGroupFields: ['region'],
    valueFields: [{ field: 'sales', aggFunc: 'sum' }],
    sortRows: { by: 'label', direction: 'asc' },    // sort row groups alphabetically
    sortColumns: 'desc',                              // sort column keys descending
  },
}
```

`sortRows` accepts `{ by: 'label' | 'value', direction: 'asc' | 'desc', valueField?: string }`.
When `by` is `'value'`, rows are sorted by their total (or by a specific `valueField`).

## Default Expanded

Control which groups start expanded:

```ts
features: {
  pivot: {
    defaultExpanded: true,           // all groups (default)
    defaultExpanded: false,          // all collapsed
    defaultExpanded: 'North',        // expand only the 'North' group
    defaultExpanded: ['North', 'South'], // expand specific groups
    defaultExpanded: 0,              // expand group at index 0
  },
}
```

## Grand Total in Row Model

By default, the grand total renders as a sticky footer. To include it in the row model
(useful for exports and copy/paste):

```ts
features: {
  pivot: {
    showGrandTotal: true,
    grandTotalInRowModel: true,
  },
}
```

## Events

| Event | Detail | Description |
| --- | --- | --- |
| `pivot-toggle` | `{ key, expanded, label, depth }` | Fired when a group is expanded or collapsed |
| `pivot-state-change` | `{ active: boolean }` | Fired when pivot mode is enabled or disabled |
| `pivot-config-change` | `{ property, field?, zone? }` | Fired when pivot configuration changes (fields, agg func, etc.) |

```ts
grid.addEventListener('pivot-toggle', (e) => {
  console.log(`${e.detail.label} ${e.detail.expanded ? 'expanded' : 'collapsed'}`);
});

grid.addEventListener('pivot-state-change', (e) => {
  console.log(`Pivot is now ${e.detail.active ? 'active' : 'inactive'}`);
});
```

## Styling

The pivot plugin supports CSS custom properties for theming. Override these on `tbw-grid` or a parent container:

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-pivot-group-bg` | `var(--tbw-color-row-alt)` | Group row background |
| `--tbw-pivot-group-hover` | `var(--tbw-color-row-hover)` | Group row hover |
| `--tbw-pivot-leaf-bg` | `var(--tbw-color-bg)` | Leaf row background |
| `--tbw-pivot-grand-total-bg` | `var(--tbw-color-header-bg)` | Grand total row |
| `--tbw-pivot-toggle-hover-bg` | `var(--tbw-color-row-hover)` | Toggle button hover |
| `--tbw-pivot-section-bg` | `var(--tbw-color-panel-bg)` | Panel section background |
| `--tbw-toggle-size` | `1.25em` | Toggle button size |
| `--tbw-animation-duration` | `200ms` | Expand/collapse animation |

### Example

```css
tbw-grid {
  /* Custom pivot styling */
  --tbw-pivot-group-bg: #fff3e0;
  --tbw-pivot-grand-total-bg: #ffcc80;
  --tbw-pivot-toggle-hover-bg: #ffe0b2;
}
```

### CSS Classes

The pivot plugin uses these class names:

| Class | Element |
| --- | --- |
| `.pivot-group-row` | Grouped summary row |
| `.pivot-leaf-row` | Detail/leaf row |
| `.pivot-grand-total-row` | Grand total row |
| `.pivot-grand-total-footer` | Sticky footer container |
| `.pivot-toggle` | Expand/collapse button |
| `.pivot-label` | Group name display |
| `.tbw-pivot-slide-in` | Row slide animation |
| `.tbw-pivot-fade-in` | Row fade animation |

## Plugin Compatibility

:::caution[Incompatible Plugins]
The Pivot plugin **cannot** be used with the following plugins:

- **[Row Grouping](/grid/plugins/grouping-rows.md)** — Pivot creates its own aggregated row and column structure. Row grouping cannot be applied on top of pivot-generated rows.
- **[Tree](/grid/plugins/tree.md)** — Pivot replaces the entire row and column structure with aggregated data. Tree hierarchy cannot coexist with pivot aggregation.
- **[Server-Side](/grid/plugins/server-side.md)** — Pivot requires the full dataset to compute aggregations. Server-side lazy loading provides rows in blocks, so pivot aggregation cannot be performed client-side.
:::

A development-mode warning is shown if incompatible plugins are loaded together.

## See Also

- [Row Grouping](/grid/plugins/grouping-rows.md) — Group flat data by field values
- [Server-Side Plugin](/grid/plugins/server-side.md) — Lazy loading and remote data

---

# Print Plugin

> Print the grid contents with configurable page settings.

The **Print Plugin** enables printing the full grid content by temporarily disabling virtualization
and applying print-optimized styles. It handles large datasets gracefully with configurable row limits.

## Features

- **Print Layout Mode** - Optimized CSS styles for printing
- **Page Orientation** - Portrait or landscape orientation
- **Row Limits** - Configurable maximum rows with confirmation dialog for large datasets
- **Toolbar Button** - Optional print button in grid header
- **Title & Timestamp** - Optional print header with customizable title and timestamp
- **Column Hiding** - Mark columns as `printHidden` to exclude from print output

## Installation

```typescript
import '@toolbox-web/grid/features/print';
```

## Basic Usage

Use the controls to try different orientations, toggle title/timestamp, isolated printing, and the toolbar button.
Enable "Toolbar button" to add a print icon to the grid header (requires `shell.header` config).

```ts
// PrintBasicDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/print';

const container = document.getElementById('print-basic-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container)!;
  const btn = container.querySelector('#print-basic-btn');

  const employeeData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 85000, status: 'Active', email: 'alice@company.com' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 72000, status: 'Active', email: 'bob@company.com' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 92000, status: 'Active', email: 'carol@company.com' },
    { id: 4, name: 'David Brown', department: 'Sales', salary: 68000, status: 'On Leave', email: 'david@company.com' },
    { id: 5, name: 'Emma Davis', department: 'HR', salary: 65000, status: 'Active', email: 'emma@company.com' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 88000, status: 'Active', email: 'frank@company.com' },
    { id: 7, name: 'Grace Wilson', department: 'Marketing', salary: 75000, status: 'Active', email: 'grace@company.com' },
    { id: 8, name: 'Henry Taylor', department: 'Sales', salary: 70000, status: 'Active', email: 'henry@company.com' },
    { id: 9, name: 'Ivy Anderson', department: 'Finance', salary: 82000, status: 'On Leave', email: 'ivy@company.com' },
    { id: 10, name: 'Jack Thomas', department: 'Engineering', salary: 95000, status: 'Active', email: 'jack@company.com' },
  ];

  let opts: Record<string, unknown> = {
    orientation: 'landscape', button: false, includeTitle: true, includeTimestamp: true, isolate: true,
  };

  function applyConfig() {
    grid.gridConfig = {
      fitMode: 'stretch',
      ...(opts.button ? { shell: { header: { title: 'Employee Report' } } } : {}),
      columns: [
        { field: 'id', header: 'ID', width: 60 },
        { field: 'name', header: 'Name', minWidth: 150 },
        { field: 'department', header: 'Department', width: 120 },
        { field: 'email', header: 'Email', minWidth: 200 },
        { field: 'salary', header: 'Salary', width: 100, align: 'right' },
        { field: 'status', header: 'Status', width: 100 },
      ],
      features: {
        print: {
          orientation: opts.orientation as string,
          button: opts.button as boolean,
          title: 'Employee Report',
          includeTitle: opts.includeTitle as boolean,
          includeTimestamp: opts.includeTimestamp as boolean,
        },
      },
    };
    grid.rows = employeeData;
  }

  applyConfig();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    opts = e.detail.allValues;
    applyConfig();
  }) as EventListener);

  btn?.addEventListener('click', () => {
    const plugin = grid.getPluginByName('print');
    plugin?.print({ isolate: opts.isolate as boolean });
  });
}
```

#### Angular

```typescript
// Feature import - enables the [print] input
import { GridPrintDirective } from '@toolbox-web/grid-angular/features/print';
import { Component } from '@angular/core';
import { Grid, injectGrid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid, GridPrintDirective],
  template: `
    <button (click)="handlePrint()">Print Report</button>
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [print]="{ title: 'Employee Report', includeTitle: true, includeTimestamp: true }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class EmployeeGridComponent {
  grid = injectGrid();
  rows = [...];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary' },
  ];

  async handlePrint() {
    const plugin = this.grid.element()?.getPluginByName('print');
    await plugin?.print();
  }
}
```

## Configuration Options

See [`PrintConfig`](./Interfaces/PrintConfig/) for the full list of options and defaults.

## Hiding Columns in Print

Use the `printHidden` column property to exclude specific columns from print output.
This is useful for hiding action buttons, interactive elements, or columns that aren't
relevant on paper.

```typescript
import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');

grid.gridConfig = {
  columns: [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'actions', header: 'Actions', printHidden: true }, // Hidden when printing
  ],
  features: { print: true },
};
```

The `printHidden` property:
- Temporarily hides columns when `print()` is called
- Automatically restores column visibility after printing
- Preserves the original hidden state (if a column was already hidden, it stays hidden)
- Works independently of the VisibilityPlugin

### Utility (system) columns

Columns marked with [`utility: true`](/grid/core.md#system-columns) — including the
selection checkbox, expander, drag handle, and any system column you author yourself —
are hidden from print **by default**, no `printHidden` needed.

To force a utility column to appear in the printout, set `printHidden: false` explicitly:

```typescript
{ field: '__id', header: '#', utility: true, printHidden: false }
```

```ts
// PrintHiddenColumnsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/print';

const container = document.getElementById('print-hidden-columns-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);
  const btn = container.querySelector('#print-hidden-btn');

  const employeeData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 85000, email: 'alice@company.com' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 72000, email: 'bob@company.com' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 92000, email: 'carol@company.com' },
    { id: 4, name: 'David Brown', department: 'Sales', salary: 68000, email: 'david@company.com' },
    { id: 5, name: 'Emma Davis', department: 'HR', salary: 65000, email: 'emma@company.com' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 88000, email: 'frank@company.com' },
    { id: 7, name: 'Grace Wilson', department: 'Marketing', salary: 75000, email: 'grace@company.com' },
    { id: 8, name: 'Henry Taylor', department: 'Sales', salary: 70000, email: 'henry@company.com' },
  ];

  grid.gridConfig = {
    fitMode: 'stretch',
    columns: [
      { field: 'id', header: 'ID', width: 60 },
      { field: 'name', header: 'Name', minWidth: 150 },
      { field: 'department', header: 'Department', width: 120 },
      { field: 'email', header: 'Email', minWidth: 200 },
      { field: 'salary', header: 'Salary', width: 100, align: 'right' },
      {
        field: 'actions',
        header: 'Actions',
        width: 100,
        printHidden: true,
        renderer: () => {
          const btn = document.createElement('button');
          btn.textContent = 'Edit';
          btn.style.cssText = 'padding: 4px 8px; cursor: pointer;';
          return btn;
        },
      },
    ],
    features: {
      print: {
        title: 'Employee Report (Filtered)',
        includeTitle: true,
        includeTimestamp: true,
      },
    },
  };
  grid.rows = employeeData;

  btn?.addEventListener('click', () => {
    const plugin = grid.getPluginByName('print');
    plugin?.print({ isolate: true });
  });
}
```

## Row Limits

Two separate options control large dataset behavior:

- **`warnThreshold`** - Shows a confirmation dialog when row count exceeds this value,
  letting users consent to a potentially slow print operation
- **`maxRows`** - Hard-limits the printed rows to this number (excess rows are not rendered)

```ts
// PrintRowLimitDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/print';

const container = document.getElementById('print-row-limit-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);
  const btn = container.querySelector('#print-limit-btn');

  const largeDataset = Array.from({ length: 1000 }, (_, i) => ({
    id: i + 1,
    name: `Employee ${i + 1}`,
    department: ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'][i % 5],
    salary: 50000 + Math.floor(Math.random() * 50000),
  }));

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', width: 60 },
      { field: 'name', header: 'Name', width: 180 },
      { field: 'department', header: 'Department', width: 120 },
      { field: 'salary', header: 'Salary', width: 100, align: 'right' },
    ],
    features: {
      print: {
        warnThreshold: 500,
        maxRows: 100,
        title: 'Large Dataset Print Test',
      },
    },
  };
  grid.rows = largeDataset;

  btn?.addEventListener('click', () => {
    const plugin = grid.getPluginByName('print');
    plugin?.print({ isolate: true });
  });
}
```

```typescript
// Warn at 500+ rows, but print all if confirmed
features: { print: { warnThreshold: 500 } }

// Hard limit to 100 rows (no warning, just limits)
features: { print: { maxRows: 100, warnThreshold: 0 } }

// Warn at 500+ rows AND hard limit to 1000
features: { print: { warnThreshold: 500, maxRows: 1000 } }
```

The confirmation dialog shows:
- Total row count
- Note about hard limit (if `maxRows` is set)
- Option to proceed or cancel

## Events

The plugin emits events during the print lifecycle:

```ts
// PrintPrintEventsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/print';

const container = document.getElementById('print-events-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);
  const btn = container.querySelector('#print-events-btn');
  const log = container.querySelector('#print-event-log');

  const employeeData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering' },
    { id: 2, name: 'Bob Smith', department: 'Marketing' },
    { id: 3, name: 'Carol Williams', department: 'Engineering' },
    { id: 4, name: 'David Brown', department: 'Sales' },
    { id: 5, name: 'Emma Davis', department: 'HR' },
  ];

  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name' },
      { field: 'department', header: 'Department' },
    ],
    features: {
      print: {
        title: 'Event Demo',
        warnThreshold: 0,
      },
    },
  };
  grid.rows = employeeData;

  grid.on('print-start', ({ rowCount }) => {
    if (!log) return;
    const msg = document.createElement('div');
    msg.textContent = `[print-start] Preparing ${rowCount} rows...`;
    log.appendChild(msg);
  });

  grid.on('print-complete', ({ duration }) => {
    if (!log) return;
    const msg = document.createElement('div');
    msg.textContent = `[print-complete] Dialog closed after ${duration}ms`;
    log.appendChild(msg);
  });

  btn?.addEventListener('click', () => {
    const plugin = grid.getPluginByName('print');
    plugin?.print({ isolate: true });
  });
}
```

### `print-start`

Fired when print preparation begins:

```typescript
grid.on('print-start', ({ rowCount, limitApplied, originalRowCount }) => {
  console.log('Preparing rows:', rowCount);
  console.log('Limit applied:', limitApplied);
  if (limitApplied) {
    console.log('Original count:', originalRowCount);
  }
});
```

### `print-complete`

Fired when the print dialog closes:

```typescript
grid.on('print-complete', ({ duration, rowCount }) => {
  console.log('Dialog open for:', duration, 'ms');
  console.log('Rows prepared:', rowCount);
});
```

:::note
Browsers don't expose whether the user clicked "Print" or "Cancel".
The `success` field only indicates whether the plugin encountered an error
preparing the print dialog - it does NOT indicate the user's choice.
:::

## Programmatic API

### `print(params?)`

Initiates the print process. Returns a Promise that resolves when printing completes.

```typescript
const plugin = grid.getPluginByName('print');

// Basic print (prints entire page)
await plugin.print();

// With runtime overrides
await plugin.print({
  title: 'Custom Report Title',
  orientation: 'portrait',
});

// Isolated print - opens new window with only the grid
await plugin.print({ isolate: true });
```

### Print Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `orientation` | `'portrait' \| 'landscape'` | Override page orientation |
| `title` | `string` | Override print title |
| `maxRows` | `number` | Override maximum rows |
| `isolate` | `boolean` | Print with page isolation (hides all non-grid content) |

### Isolated Printing

When `isolate: true` is passed, the plugin uses CSS to hide **everything** on the page
except the grid during printing. This is useful when:

- The page has navigation, sidebars, or headers that shouldn't appear in print
- You want to print only the grid without surrounding UI
- The grid is embedded in an application framework like Storybook, Angular, etc.

```typescript
// Print just the grid, hiding all other page content
await plugin.print({ isolate: true });
```

**How it works:**
1. A temporary `@media print` stylesheet is injected
2. The stylesheet hides all elements except the grid (identified by its unique ID)
3. After printing, the stylesheet is removed
4. The grid stays in place with virtualization disabled, so ALL rows are printed

### `isPrinting()`

Returns `true` if a print operation is currently in progress.

```typescript
if (plugin.isPrinting()) {
  console.log('Print already in progress');
}
```

## Print CSS Classes

The plugin applies these CSS classes during printing:

| Class | Description |
|-------|-------------|
| `.print-portrait` | Applied when orientation is portrait |
| `.print-landscape` | Applied when orientation is landscape |
| `.tbw-print-header` | Print header container |
| `.tbw-print-header-title` | Title element |
| `.tbw-print-header-timestamp` | Timestamp element |

## Custom Print Styles

Override print styles using CSS:

```css
@media print {
  tbw-grid.print-landscape {
    /* Custom print styles */
    font-size: 10pt;
  }

  tbw-grid.print-landscape .dg-cell {
    border-color: #000;
  }
}
```

## How It Works

1. **Disable Virtualization** - Temporarily renders all rows (up to `maxRows`)
2. **Apply Print Styles** - Adds print-mode CSS class and orientation class
3. **Add Print Header** - Inserts title and timestamp (if configured)
4. **Trigger Print** - Calls `window.print()`
5. **Cleanup** - Restores virtualization and removes temporary elements

## Browser Support

The Print Plugin uses standard browser printing APIs (`window.print()`, `@media print`)
and works in all modern browsers:

- Chrome / Edge (Chromium)
- Firefox
- Safari

## Best Practices

1. **Set reasonable `maxRows`** - Consider limiting to ~5000 rows to prevent browser hangs
2. **Use landscape for wide grids** - More columns fit horizontally
3. **Test print preview** - Use browser's print preview to verify layout
4. **Custom titles** - Provide meaningful titles for printed reports
5. **Use `printHidden` for interactive columns** - Hide action buttons, checkboxes, etc.
6. **Use `isolate: true`** - When other page content interferes with print layout

## Standalone Utility Function

For simple use cases where you don't need the full plugin, use the standalone
`printGridIsolated` function:

```typescript
import { queryGrid } from '@toolbox-web/grid';
import { printGridIsolated } from '@toolbox-web/grid/plugins/print';

const grid = queryGrid('tbw-grid');
await printGridIsolated(grid, {
  orientation: 'landscape',
});
```

This function injects a temporary CSS stylesheet that hides everything except
the target grid during printing. The grid must have an `id` attribute (DataGridElement
auto-generates one if not explicitly set).

**Note:** Unlike the PrintPlugin, this function does NOT disable virtualization.
If you need to print all rows, use the full PrintPlugin with `isolate: true`.

## See Also

- **[Export](/grid/plugins/export.md)** — Export to CSV/JSON
- **[Selection](/grid/plugins/selection.md)** — Row/cell selection

---

# Column Reorder Plugin

> Allow users to reorder columns by drag and drop.

The Reorder plugin lets users rearrange columns by dragging and dropping column headers. Supports smooth FLIP animations, fade transitions, or instant reordering depending on your preference.

## Installation

```ts
import '@toolbox-web/grid/features/reorder-columns';
```

## Basic Usage

Just enable the feature and columns become draggable. Users can grab any column header and drop it in a new position. Visual feedback and smooth animations are handled automatically.

#### Angular

```typescript
// Feature import - enables the [reorder] input
import { GridReorderColumnsDirective } from '@toolbox-web/grid-angular/features/reorder-columns';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridReorderColumnsDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [reorderColumns]="{ animation: 'flip' }"
      (column-move)="onColumnMove($event)"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [...];

  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
  ];

  onColumnMove(e: CustomEvent) {
    console.log(`Moved ${e.detail.field} from ${e.detail.fromIndex} to ${e.detail.toIndex}`);
  }
}
```

## Demos

### Default Reorder

```ts
// ReorderDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/reorder-columns';

const container = document.getElementById('reorder-default-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice', department: 'Engineering', email: 'alice@example.com', salary: 95000 },
    { id: 2, name: 'Bob', department: 'Marketing', email: 'bob@example.com', salary: 75000 },
    { id: 3, name: 'Carol', department: 'Engineering', email: 'carol@example.com', salary: 105000 },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'email', header: 'Email' },
    { field: 'salary', header: 'Salary', type: 'number' },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(animation = 'flip', animationDuration = 200) {
    grid.gridConfig = {
      columns,
      features: { reorderColumns: { animation, animationDuration } as any },
    };
    grid.rows = sampleData;
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    const v = e.detail.allValues;
    rebuild(v.animation as string, v.animationDuration as number);
  }) as EventListener);
}
```

Drag column headers to reorder them. Use the controls below to experiment with different animation types and durations.

## Configuration Options

See [`ReorderConfig`](./interfaces/reorderconfig/) for the full list of options and defaults.

### Animation Examples

```ts
// No animation - instant reorder
features: { reorderColumns: { animation: false } }

// FLIP animation with custom duration
features: { reorderColumns: { animation: 'flip', animationDuration: 300 } }

// View Transitions API fade effect
features: { reorderColumns: { animation: 'fade' } }
```

### Locking Individual Columns

Set `lockPosition: true` on any column to prevent users from dragging it — both in the
header row and in the [Column Visibility](../visibility/) panel. Programmatic reorder
via `grid.setColumnOrder()` still works.

```ts
columns: [
  { field: 'id', header: 'ID', lockPosition: true }, // cannot be moved
  { field: 'name', header: 'Name' },
  { field: 'email', header: 'Email' },
]
```

## Events

```ts
// ReorderColumnsEventsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/reorder-columns';

const container = document.getElementById('reorder-columns-events-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name' },
      { field: 'department', header: 'Department' },
      { field: 'role', header: 'Role' },
      { field: 'salary', header: 'Salary', type: 'number', align: 'right' },
    ],
    features: { reorderColumns: true },
  };

  grid.rows = [
    { name: 'Alice Johnson', department: 'Engineering', role: 'Lead', salary: 95000 },
    { name: 'Bob Smith', department: 'Marketing', role: 'Manager', salary: 75000 },
    { name: 'Carol White', department: 'Sales', role: 'Rep', salary: 68000 },
    { name: 'David Brown', department: 'Engineering', role: 'Senior', salary: 92000 },
    { name: 'Eve Davis', department: 'HR', role: 'Specialist', salary: 65000 },
  ];

  const log = container.querySelector('#reorder-col-events-log');
  const clearBtn = container.querySelector('#clear-reorder-col-events-log');

  function addLog(type: string, detail: string) {
    if (!log) return;
    const msg = document.createElement('div');
    msg.innerHTML = `<span class="event-type">[${type}]</span> ${detail}`;
    log.insertBefore(msg, log.firstChild);
    while (log.children.length > 15) log.lastChild?.remove();
  }

  clearBtn?.addEventListener('click', () => { if (log) log.innerHTML = ''; });

  grid.on('column-move', (d) => {
    addLog('column-move', `"${d.field}" from index ${d.fromIndex} → ${d.toIndex}`);
  });
}
```

| Event         | Detail                                        | Cancelable | Description                                       |
| ------------- | --------------------------------------------- | ---------- | ------------------------------------------------- |
| `column-move` | `{ field, fromIndex, toIndex, columnOrder }` | Yes        | Fired when a column move is attempted. Call `preventDefault()` to block the move. |

## Keyboard Shortcuts

| Key       | Action                    |
| --------- | ------------------------- |
| `Alt + ←` | Move focused column left  |
| `Alt + →` | Move focused column right |

## Column Group Drag

When [Column Grouping](../grouping-columns/) is also active, group header cells become draggable.
Dragging a group header moves all columns in that fragment as a block. If a group is fragmented
(split across non-contiguous positions), each fragment can be dragged independently.

## See Also

- **[Pinned Columns](/grid/plugins/pinned-columns.md)** — Sticky columns
- **[Column Visibility](../visibility/)** — Show/hide columns
- **[Column Groups](../grouping-columns/)** — Group column headers

---

# Row Reorder Plugin (deprecated)

> Deprecated alias for the Row Drag-Drop plugin.

:::caution[Deprecated — superseded by Row Drag-Drop]
`RowReorderPlugin` and the `reorderRows` feature key are now aliases for the
new [`RowDragDropPlugin`](/grid/plugins/row-drag-drop.md), which is a strict
superset (intra-grid reorder + opt-in cross-grid drag).

All existing imports, feature keys, configuration options, events, CSS
variables, and demos continue to work unchanged until V3 — the alias is
resolved at plugin attach time and there is no behavioural difference.
:::

## What changed

- The implementation moved from `@toolbox-web/grid/plugins/reorder-rows` to
  [`@toolbox-web/grid/plugins/row-drag-drop`](/grid/plugins/row-drag-drop.md).
- The feature key `reorderRows` is now a deprecated alias for `rowDragDrop`.
- The legacy `canMove` callback is preserved and mapped internally to the
  new `canDrop` hook with a synthesised intra-grid payload.
- The plugin's name is now `'rowDragDrop'`. `getPluginByName('reorderRows')`
  still resolves to the same instance.

## Where to go next

- **Documentation, demos, configuration, events, and the migration guide**
  all live on the
  [Row Drag-Drop Plugin page](/grid/plugins/row-drag-drop.md).
- **Code migration** — see the
  [migration section](/grid/plugins/row-drag-drop.md#migration-from-rowreorderplugin)
  for the one-line import swap.

If you have no need for cross-grid drag or any of the new
`row-drag-start` / `row-drop` / `row-transfer` events, no code change is
required to keep the existing intra-grid reorder behaviour working — the
alias takes care of it.

---

# Responsive Plugin

> Automatically adapt the grid layout for different screen sizes.

The Responsive plugin transforms the grid from a tabular layout to a card/list layout when the grid width falls below a configurable breakpoint. This enables grids to work seamlessly in narrow containers like split-pane UIs, mobile viewports, and dashboard widgets.

## Installation

```ts
import '@toolbox-web/grid/features/responsive';
```

## Basic Usage

#### Angular

```typescript
// Feature import - enables the [responsive] input
import { GridResponsiveDirective } from '@toolbox-web/grid-angular/features/responsive';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridResponsiveDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [responsive]="{ breakpoint: 500 }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob', email: 'bob@example.com' },
  ];

  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ];
}
```

## Demos

### Interactive Demo

```ts
// ResponsiveDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/responsive';

const container = document.getElementById('responsive-default-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, email: 'alice@example.com', startDate: '2020-03-15' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, email: 'bob@example.com', startDate: '2019-07-22' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, email: 'carol@example.com', startDate: '2018-11-01' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, email: 'dan@example.com', startDate: '2021-01-10' },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000, email: 'eve@example.com', startDate: '2022-05-03' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000, email: 'frank@example.com', startDate: '2020-08-20' },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number', width: 60 },
    { field: 'name', header: 'Name', width: 150 },
    { field: 'department', header: 'Department', width: 120 },
    { field: 'salary', header: 'Salary', type: 'number', width: 100 },
    { field: 'email', header: 'Email', width: 200 },
    { field: 'startDate', header: 'Start Date', width: 120 },
  ];

  const grid = queryGrid('tbw-grid', container)!;
  const status = container.querySelector('.responsive-status')!;
  let currentBreakpoint = 500;

  function rebuild(breakpoint = 500, hideHeader = false, animate = true, hiddenColumns: string[] = [], debounceMs = 100) {
    currentBreakpoint = breakpoint;
    grid.gridConfig = {
      columns,
      features: { responsive: { breakpoint, hideHeader, animate, hiddenColumns, debounceMs } },
    };
    grid.rows = sampleData;
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    const v = e.detail.allValues;
    rebuild(v.breakpoint as number, v.hideHeader as boolean, v.animate as boolean, v.hiddenColumns as string[], v.debounceMs as number);
  }) as EventListener);

  grid.on('responsive-change', ({ isResponsive, width, breakpoint }) => {
    status.textContent = `Mode: ${isResponsive ? '📱 Card' : '📊 Table'} | Width: ${Math.round(width)}px | Breakpoint: ${breakpoint}px`;
  });

  requestAnimationFrame(() => {
    const width = grid.clientWidth;
    status.textContent = `Mode: ${width < currentBreakpoint ? '📱 Card' : '📊 Table'} | Width: ${Math.round(width)}px | Breakpoint: ${currentBreakpoint}px`;
  });
}
```

Resize the container to see the grid switch between table and card layouts.

### Manual Control

```ts
// ResponsiveManualControlDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/responsive';

const container = document.getElementById('responsive-manual-control-demo');
if (container) {
  // Sample data
  const sampleData = [
    {
      id: 1,
      name: 'Alice Johnson',
      department: 'Engineering',
      salary: 95000,
      email: 'alice@example.com',
      startDate: '2020-03-15',
    },
    {
      id: 2,
      name: 'Bob Smith',
      department: 'Marketing',
      salary: 75000,
      email: 'bob@example.com',
      startDate: '2019-07-22',
    },
    {
      id: 3,
      name: 'Carol Williams',
      department: 'Engineering',
      salary: 105000,
      email: 'carol@example.com',
      startDate: '2018-11-01',
    },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, email: 'dan@example.com', startDate: '2021-01-10' },
    {
      id: 5,
      name: 'Eve Davis',
      department: 'Marketing',
      salary: 72000,
      email: 'eve@example.com',
      startDate: '2022-05-03',
    },
    {
      id: 6,
      name: 'Frank Miller',
      department: 'Engineering',
      salary: 98000,
      email: 'frank@example.com',
      startDate: '2020-08-20',
    },
  ];
  const columns = [
    { field: 'id', header: 'ID', type: 'number', width: 60 },
    { field: 'name', header: 'Name', width: 150 },
    { field: 'department', header: 'Department', width: 120 },
    { field: 'salary', header: 'Salary', type: 'number', width: 100 },
    { field: 'email', header: 'Email', width: 200 },
    { field: 'startDate', header: 'Start Date', width: 120 },
  ];

  // Controls
      const controls = container.querySelector('[data-controls-id="responsive-manual-control-demo"]');
      controls.style.cssText = 'margin-bottom: 12px; display: flex; gap: 8px;';

      const tableBtn = document.createElement('button');
      tableBtn.textContent = '📊 Table Mode';
      tableBtn.style.cssText = 'padding: 8px 16px; cursor: pointer;';

      const cardBtn = document.createElement('button');
      cardBtn.textContent = '📱 Card Mode';
      cardBtn.style.cssText = 'padding: 8px 16px; cursor: pointer;';

      controls.appendChild(tableBtn);
      controls.appendChild(cardBtn);

      const grid = queryGrid('tbw-grid', container);

      grid.gridConfig = {
        columns: columns.slice(0, 4), // Fewer columns
        features: { responsive: { breakpoint: 0 } },
      };
      grid.rows = sampleData;

      tableBtn.addEventListener('click', () => grid.getPluginByName('responsive')?.setResponsive(false));
      cardBtn.addEventListener('click', () => grid.getPluginByName('responsive')?.setResponsive(true));
}
```

Use the plugin API to manually control responsive mode.

### Custom Card Renderer

```ts
// ResponsiveCustomCardRendererDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/responsive';

const container = document.getElementById('responsive-custom-card-renderer-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);
  const status = container.querySelector('.responsive-status');
  if (!grid) throw new Error('Grid not found');

  interface Employee {
    id: number;
    name: string;
    department: string;
    salary: number;
    email: string;
    startDate: string;
  }

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 60 },
      { field: 'name', header: 'Name', width: 150 },
      { field: 'department', header: 'Department', width: 120 },
      { field: 'salary', header: 'Salary', type: 'number', width: 100 },
      { field: 'email', header: 'Email', width: 200 },
      { field: 'startDate', header: 'Start Date', width: 120 },
    ],
    features: {
      responsive: {
        breakpoint: 600,
        cardRenderer: (row: Employee) => {
          const card = document.createElement('div');
          card.className = 'employee-card';
          const deptClass = row.department.toLowerCase().replace(/\s+/g, '-');
          card.innerHTML = `
            <div class="avatar">${row.name[0]}</div>
            <div class="info">
              <div class="name">
                ${row.name}
                <span class="badge ${deptClass}">${row.department}</span>
              </div>
              <div class="meta">$${row.salary.toLocaleString()} · Started ${row.startDate}</div>
              <div class="email">${row.email}</div>
            </div>
          `;
          return card;
        },
      },
    },
  };

  grid.rows = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, email: 'alice@example.com', startDate: '2020-03-15' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, email: 'bob@example.com', startDate: '2019-07-22' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, email: 'carol@example.com', startDate: '2018-11-01' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, email: 'dan@example.com', startDate: '2021-01-10' },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000, email: 'eve@example.com', startDate: '2022-05-03' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000, email: 'frank@example.com', startDate: '2020-08-20' },
  ];

  grid.on('responsive-change', ({ isResponsive, width }) => {
    if (!status) return;
    status.textContent = `Mode: ${isResponsive ? '📱 Custom Cards' : '📊 Table'} | Width: ${Math.round(width)}px`;
  });

  requestAnimationFrame(() => {
    if (!status) return;
    const width = grid.clientWidth;
    status.textContent = `Mode: ${width < 600 ? '📱 Custom Cards' : '📊 Table'} | Width: ${Math.round(width)}px`;
  });
}
```

Use `cardRenderer` for complete control over card layout - avatars, badges, custom layouts, etc.

### Fixed Card Height

```ts
// ResponsiveFixedCardHeightDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/responsive';

const container = document.getElementById('responsive-fixed-card-height-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);
  if (!grid) throw new Error('Grid not found');

  interface Employee {
    id: number;
    name: string;
    department: string;
    salary: number;
    email: string;
    startDate: string;
  }

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 60 },
      { field: 'name', header: 'Name', width: 150 },
      { field: 'department', header: 'Department', width: 120 },
      { field: 'salary', header: 'Salary', type: 'number', width: 100 },
    ],
    features: {
      responsive: {
        breakpoint: 500,
        cardRowHeight: 60,
        cardRenderer: (row: Employee) => {
          const card = document.createElement('div');
          card.className = 'simple-card';
          card.innerHTML = `
            <div class="initial">${row.name[0]}</div>
            <div class="details">
              <div class="name">${row.name}</div>
              <div class="dept">${row.department}</div>
            </div>
          `;
          return card;
        },
      },
    },
  };

  grid.rows = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, email: 'alice@example.com', startDate: '2020-03-15' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, email: 'bob@example.com', startDate: '2019-07-22' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, email: 'carol@example.com', startDate: '2018-11-01' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, email: 'dan@example.com', startDate: '2021-01-10' },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000, email: 'eve@example.com', startDate: '2022-05-03' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000, email: 'frank@example.com', startDate: '2020-08-20' },
  ];
}
```

Use `cardRowHeight` for consistent card heights, which helps virtualization performance.

### Progressive Degradation

```ts
// ResponsiveProgressiveDegradationDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/responsive';

const container = document.getElementById('responsive-progressive-degradation-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);
  const status = container.querySelector('.responsive-status');
  if (!grid) throw new Error('Grid not found');

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 60 },
      { field: 'name', header: 'Name', width: 150 },
      { field: 'department', header: 'Department', width: 120 },
      { field: 'salary', header: 'Salary', type: 'number', width: 100 },
      { field: 'email', header: 'Email', width: 200 },
      { field: 'startDate', header: 'Start Date', width: 120 },
    ],
    features: {
      responsive: {
        breakpoints: [
          { maxWidth: 900, hiddenColumns: ['startDate'] },
          { maxWidth: 700, hiddenColumns: ['startDate', 'email'] },
          { maxWidth: 500, hiddenColumns: ['startDate', 'email', 'salary'] },
          { maxWidth: 400, cardLayout: true },
        ],
      },
    },
  };

  grid.rows = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, email: 'alice@example.com', startDate: '2020-03-15' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, email: 'bob@example.com', startDate: '2019-07-22' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, email: 'carol@example.com', startDate: '2018-11-01' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, email: 'dan@example.com', startDate: '2021-01-10' },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000, email: 'eve@example.com', startDate: '2022-05-03' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000, email: 'frank@example.com', startDate: '2020-08-20' },
  ];

  const updateStatus = () => {
    if (!status) return;
    const plugin = grid.getPluginByName('responsive');
    const bp = plugin?.getActiveBreakpoint();
    const isCard = plugin?.isResponsive();
    if (!bp) {
      status.textContent = '📊 Full Table (no columns hidden)';
    } else if (isCard) {
      status.textContent = `📱 Card Layout (≤${bp.maxWidth}px)`;
    } else {
      const hidden = bp.hiddenColumns?.length ?? 0;
      status.textContent = `📊 Table - ${hidden} column(s) hidden (≤${bp.maxWidth}px)`;
    }
  };

  grid.on('responsive-change', updateStatus);
  requestAnimationFrame(updateStatus);
}
```

Use multiple breakpoints to progressively hide columns before switching to card layout.

### Value-Only Columns

```ts
// ResponsiveValueOnlyColumnsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/responsive';

const container = document.getElementById('responsive-value-only-columns-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);
  if (!grid) throw new Error('Grid not found');

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 60 },
      { field: 'name', header: 'Name', width: 150 },
      { field: 'department', header: 'Department', width: 120 },
      { field: 'salary', header: 'Salary', type: 'number', width: 100 },
      { field: 'email', header: 'Email', width: 200 },
      { field: 'startDate', header: 'Start Date', width: 120 },
    ],
    features: {
      responsive: {
        breakpoint: 500,
        hiddenColumns: ['startDate', { field: 'email', showValue: true }],
      },
    },
  };

  grid.rows = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000, email: 'alice@example.com', startDate: '2020-03-15' },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000, email: 'bob@example.com', startDate: '2019-07-22' },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000, email: 'carol@example.com', startDate: '2018-11-01' },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000, email: 'dan@example.com', startDate: '2021-01-10' },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000, email: 'eve@example.com', startDate: '2022-05-03' },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000, email: 'frank@example.com', startDate: '2020-08-20' },
  ];
}
```

Use enhanced `hiddenColumns` syntax to show values without labels.

### Animated Transitions

```ts
// ResponsiveAnimatedTransitionsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/responsive';

const container = document.getElementById('responsive-animated-transitions-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);
  const status = container.querySelector('.responsive-status');
  if (!grid) throw new Error('Grid not found');

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 60 },
      { field: 'name', header: 'Name', width: 150 },
      { field: 'department', header: 'Department', width: 120 },
      { field: 'salary', header: 'Salary', type: 'number', width: 100 },
    ],
    features: {
      responsive: {
        breakpoint: 500,
        animate: true,
        animationDuration: 300,
      },
    },
  };

  grid.rows = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000 },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 75000 },
    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 105000 },
    { id: 4, name: 'Dan Brown', department: 'Sales', salary: 85000 },
    { id: 5, name: 'Eve Davis', department: 'Marketing', salary: 72000 },
    { id: 6, name: 'Frank Miller', department: 'Engineering', salary: 98000 },
  ];

  grid.on('responsive-change', ({ isResponsive }) => {
    if (status) status.textContent = isResponsive ? '📱 Card mode - watch the fade-in animation!' : '📊 Table mode';
  });
}
```

Smooth animations when transitioning between modes (enabled by default).

## Light DOM Configuration

The ResponsivePlugin supports declarative configuration via the `<tbw-grid-responsive-card>` element. Framework adapters provide wrapper components with idiomatic rendering patterns.

#### Angular

```html
<tbw-grid [rows]="data" [columns]="columns" [responsive]="{ breakpoint: 500 }">
  <tbw-grid-responsive-card>
    <ng-template let-row let-index="index">
      <div class="custom-card">
        <strong>{{ row.name }}</strong>
        <span>{{ row.email }}</span>
      </div>
    </ng-template>
  </tbw-grid-responsive-card>
</tbw-grid>
```

Angular uses `<ng-template>` with implicit context binding (`let-row`, `let-index="index"`). Import `GridResponsiveCard` from `@toolbox-web/grid-angular`.

### Vanilla Attributes

| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `breakpoint` | `number` | Width threshold in pixels for responsive mode |
| `card-row-height` | `number \| 'auto'` | Card height in pixels or auto |
| `hidden-columns` | `string` | Comma-separated field names to hide |
| `hide-header` | `'true' \| 'false'` | Hide the per-card field label (e.g. `Name:`). Default `'false'`. Does not affect the column header row, which is always hidden in card mode. |
| `debounce-ms` | `number` | Resize debounce delay in ms |

:::note
Light DOM attributes override constructor config when both are present.
:::

## Configuration Options

See [`ResponsivePluginConfig`](./Interfaces/ResponsivePluginConfig/) for the full list of options and defaults.

### BreakpointConfig

For progressive degradation, use the `breakpoints` array instead of a single `breakpoint`. See [`BreakpointConfig`](./Interfaces/BreakpointConfig/) for the full interface.

### HiddenColumnConfig

The enhanced `hiddenColumns` syntax supports both simple strings and objects. See [`HiddenColumnConfig`](./Types/HiddenColumnConfig/) for the full type definition.

**Example:**
```ts
hiddenColumns: [
  'startDate',                        // Fully hidden
  { field: 'email', showValue: true }, // Value shown without label
]
```

### Choosing a Breakpoint

The breakpoint should be based on your grid's column count and content:

| Grid Size | Suggested Breakpoint |
| --------- | -------------------- |
| 3-5 columns | 400-500px |
| 6-10 columns | 600-800px |
| 10+ columns | 900-1200px |

:::note
If no breakpoint is configured (or set to 0), a warning is logged and responsive mode is effectively disabled.
:::

## Events

```ts
// ResponsiveEventsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/responsive';

const container = document.getElementById('responsive-events-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name' },
      { field: 'department', header: 'Department' },
      { field: 'salary', header: 'Salary', type: 'number', align: 'right' },
    ],
    features: {
      responsive: { breakpoint: 600 },
    },
  };

  grid.rows = [
    { name: 'Alice Johnson', department: 'Engineering', salary: 95000 },
    { name: 'Bob Smith', department: 'Marketing', salary: 75000 },
    { name: 'Carol White', department: 'Sales', salary: 68000 },
    { name: 'David Brown', department: 'Engineering', salary: 92000 },
    { name: 'Eve Davis', department: 'HR', salary: 65000 },
  ];

  const log = container.querySelector('#responsive-events-log');
  const clearBtn = container.querySelector('#clear-responsive-events-log');

  function addLog(type: string, detail: string) {
    if (!log) return;
    const msg = document.createElement('div');
    msg.innerHTML = `<span class="event-type">[${type}]</span> ${detail}`;
    log.insertBefore(msg, log.firstChild);
    while (log.children.length > 15) log.lastChild?.remove();
  }

  clearBtn?.addEventListener('click', () => { if (log) log.innerHTML = ''; });

  grid.on('responsive-change', (d) => {
    addLog('responsive-change', `mode: ${d.mode}, width: ${d.width}px`);
  });
}
```

### responsive-change

Emitted when the grid crosses the breakpoint threshold:

```ts
grid.on('responsive-change', ({ isResponsive, width, breakpoint }) => {
  console.log(isResponsive ? 'Card mode' : 'Table mode');
  console.log(`Width: ${width}px, Breakpoint: ${breakpoint}px`);
});
```

## Programmatic API

Control responsive mode programmatically via the plugin instance:

```ts
// Get the plugin instance from the grid
const plugin = grid.getPluginByName('responsive');

// Check current mode
const isCardMode = plugin.isResponsive();

// Force responsive mode (regardless of width)
plugin.setResponsive(true);
plugin.setResponsive(false);

// Update breakpoint dynamically
plugin.setBreakpoint(600);

// Get current grid width
const width = plugin.getWidth();

// Get active breakpoint (multi-breakpoint mode)
const activeBreakpoint = plugin.getActiveBreakpoint();
// Returns: { maxWidth: 600, hiddenColumns: [...], cardLayout: false } or null
```

## How It Works

1. **ResizeObserver** monitors the grid element's width
2. When `width < breakpoint`, the plugin adds `data-responsive` attribute to the grid
3. **CSS transforms** cells from horizontal to vertical layout
4. Each cell displays "Header: Value" using the `::before` pseudo-element with `data-header` attribute

This CSS-only approach means:
- No DOM replacement or re-rendering needed
- Smooth transitions between modes
- Works with all other plugins (selection, editing, etc.)

## Styling

The responsive plugin uses the grid's existing CSS custom properties for theming.

### CSS Custom Properties

The responsive plugin uses the grid's built-in CSS variables:

| Property | Description |
| -------- | ----------- |
| `--tbw-cell-padding` | Padding inside card rows |
| `--tbw-color-border` | Card separator color |
| `--tbw-color-bg` | Card background color |
| `--tbw-color-row-alt` | Alternating card background |
| `--tbw-color-row-hover` | Card hover background |
| `--tbw-color-selection` | Selected card background |
| `--tbw-color-header-fg` | Label text color |
| `--tbw-color-accent` | Selection indicator color |

### Custom Card Styling

```css
/* Custom card styling */
tbw-grid[data-responsive] .data-grid-row {
  border-radius: 8px;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  margin-bottom: 8px;
}

/* Hide specific columns in card mode */
tbw-grid[data-responsive] .cell[data-field="createdAt"],
tbw-grid[data-responsive] .cell[data-field="updatedAt"] {
  display: none;
}
```

### Data Attributes

| Attribute | Element | Description |
| --------- | ------- | ----------- |
| `data-responsive` | `tbw-grid` | Present when in responsive (card) mode |
| `data-responsive-animate` | `tbw-grid` | Present when animations are enabled |
| `data-header` | `.cell` | Column header text for CSS `::before` |
| `data-responsive-hidden` | `.cell` | Marks cells hidden via `hiddenColumns` |
| `data-responsive-value-only` | `.cell` | Marks cells showing value only (no label) |

### CSS Custom Properties for Animation

| Property | Default | Description |
| -------- | ------- | ----------- |
| `--tbw-responsive-duration` | `200ms` | Animation duration for mode transitions |

## Keyboard Shortcuts

In responsive mode, the visual layout is inverted - cells are stacked vertically within each card. The plugin automatically adjusts keyboard navigation to match this layout:

| Key | Table Mode | Responsive Mode |
| --- | ---------- | --------------- |
| **↑** | Previous row | Previous field (within card), wraps to previous card |
| **↓** | Next row | Next field (within card), wraps to next card |
| **←** | Previous column | Previous card (same field) |
| **→** | Next column | Next card (same field) |
| **Tab** | Next cell, wraps to next row | Same behavior |
| **Enter** | Start editing | Same behavior |
| **Escape** | Cancel editing | Same behavior |

### Custom Card Renderers

When using `cardRenderer` (Phase 2), the grid's built-in keyboard navigation is disabled for arrow keys. Implementors should handle navigation within their custom card content via their own event handlers.

## Use Cases

### Split-Pane UI

```ts
// Grid in a resizable panel
features: {
  responsive: {
    breakpoint: 400,
    hiddenColumns: ['createdAt', 'updatedAt'], // Hide dates in card mode
  },
},
```

### Mobile-First Design

```ts
// Responsive grid for mobile/tablet
features: {
  responsive: {
    breakpoint: 768,
    hideHeader: true,
  },
},
```

### Dashboard Widget

```ts
// Small widget in dashboard
features: {
  responsive: {
    breakpoint: 300,
    hiddenColumns: ['email', 'phone', 'address'],
  },
},
```

### Progressive Degradation

```ts
// Gracefully degrade as container shrinks
features: {
  responsive: {
    breakpoints: [
      { maxWidth: 900, hiddenColumns: ['startDate'] },
      { maxWidth: 700, hiddenColumns: ['startDate', 'email'] },
      { maxWidth: 500, cardLayout: true },
    ],
  },
},
```

## Custom Card Renderer

For advanced card layouts with avatars, badges, or custom grouped fields, use the `cardRenderer` option:

```ts
features: {
  responsive: {
    breakpoint: 600,
    cardRenderer: (row, rowIndex) => {
      const card = document.createElement('div');
      card.className = 'employee-card';
      card.innerHTML = `
        <div class="avatar">${row.name[0]}</div>
        <div class="info">
          <div class="name">${row.name}</div>
          <div class="meta">${row.department} · $${row.salary.toLocaleString()}</div>
          <div class="email">${row.email}</div>
        </div>
      `;
      return card;
    },
  },
},
```

### cardRenderer Signature

```ts
cardRenderer: (row: T, rowIndex: number) => HTMLElement
```

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `row` | `T` | The row data object |
| `rowIndex` | `number` | Index of the row in the data array |
| **Returns** | `HTMLElement` | The element to render as the card content |

### cardRowHeight

When using `cardRenderer`, you can control card height:

```ts
// Fixed height (better for virtualization with large datasets)
features: {
  responsive: {
    breakpoint: 600,
    cardRowHeight: 80,  // 80px per card
    cardRenderer: (row) => { /* ... */ },
  },
},

// Auto height (default - cards size to content)
features: {
  responsive: {
    breakpoint: 600,
    cardRowHeight: 'auto',
    cardRenderer: (row) => { /* ... */ },
  },
},
```

### Keyboard Navigation with cardRenderer

When using a custom `cardRenderer`, the grid's built-in arrow key navigation is disabled. This allows you to implement your own navigation within the card content.

Standard keyboard shortcuts still work:
- **Tab** - Move between cards
- **Enter** - Triggers `cell-activate` event
- **Escape** - Standard escape handling

## See Also

- **[Selection](../selection/)** — Row and cell selection
- **[Theming](../../guides/theming/)** — CSS custom properties for styling

---

# Row Drag-Drop Plugin

> Drag rows within a single grid (reorder) and across grids that share a drop zone.

The Row Drag-Drop plugin lets users rearrange rows by dragging a grip handle
or using keyboard shortcuts, and — when opted in via `dropZone` — drag rows
between separate grids. It is a strict superset of the (now deprecated)
`RowReorderPlugin`: every existing intra-grid behaviour is preserved.

- **Intra-grid** — drag a row up or down to reorder, or use `Ctrl + ↑/↓`.
- **Drag origin** — choose whether drags start from the dedicated handle
  column (`dragFrom: 'handle'`, default), from anywhere on the row
  (`dragFrom: 'row'` — handle column hidden), or from both
  (`dragFrom: 'both'`). Interactive descendants (buttons, inputs, links,
  `[contenteditable]`) inside the row are still respected and never start
  a drag.
- **Cross-grid** — set a `dropZone` to allow dragging rows to another grid
  with the same `dropZone`. Supports `move` and `copy` operations.
- **Multi-row** — when the [Selection](../selection/) plugin is loaded and
  the dragged row is part of a multi-row selection, all selected rows are
  dragged together and a count badge appears on the drag image. There is
  no `selection` config option — the behaviour is automatic.
- **Cross-window** — drag rows between separate browser windows or tabs
  on the same origin. The payload travels via `dataTransfer`, and a
  same-origin `BroadcastChannel` coordinates the source-side row removal
  for `operation: 'move'` and the source-side `row-transfer` event.

## Installation

```ts
import '@toolbox-web/grid/features/row-drag-drop';
```

The legacy `reorderRows` feature key continues to work and forwards to the
same plugin instance.

## Basic Usage

Enable the feature and a drag handle column appears automatically. Users can
drag rows to new positions or use `Ctrl + ↑/↓` to move the focused row.

#### Angular

```typescript
// Feature import - enables the [rowDragDrop] input
import { GridRowDragDropDirective } from '@toolbox-web/grid-angular/features/row-drag-drop';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-task-list',
  imports: [Grid, GridRowDragDropDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [rowDragDrop]="true"
      (rowMove)="onRowMove($event)"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class TaskListComponent {
  rows = [
    { priority: 1, task: 'Review PR', status: 'Pending' },
    { priority: 2, task: 'Deploy staging', status: 'In Progress' },
  ];

  columns: ColumnConfig[] = [
    { field: 'priority', header: '#', type: 'number', width: 50 },
    { field: 'task', header: 'Task' },
    { field: 'status', header: 'Status' },
  ];

  onRowMove(detail: any) {
    console.log('Row moved:', detail);
  }
}
```

## Demos

### Default Drag-Drop

```ts
// RowDragDropDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/row-drag-drop';

const container = document.getElementById('row-drag-drop-default-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice', department: 'Engineering', email: 'alice@example.com', priority: 1 },
    { id: 2, name: 'Bob', department: 'Marketing', email: 'bob@example.com', priority: 2 },
    { id: 3, name: 'Carol', department: 'Engineering', email: 'carol@example.com', priority: 3 },
    { id: 4, name: 'David', department: 'Sales', email: 'david@example.com', priority: 4 },
    { id: 5, name: 'Eve', department: 'Engineering', email: 'eve@example.com', priority: 5 },
  ];
  const columns = [
    { field: 'priority', header: '#', type: 'number', width: 50 },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'email', header: 'Email' },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(dragFrom = 'handle', dragHandlePosition = 'left', enableKeyboard = true, animation = 'flip') {
    grid.gridConfig = {
      columns,
      features: { rowDragDrop: { dragFrom, dragHandlePosition, enableKeyboard, animation: animation === 'false' ? false : animation } as any },
    };
    grid.rows = sampleData;
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    const v = e.detail.allValues;
    rebuild(v.dragFrom as string, v.dragHandlePosition as string, v.enableKeyboard as boolean, v.animation as string);
  }) as EventListener);
}
```

Drag the grip handle (☰) to reorder rows. Use `Ctrl + ↑/↓` to move the
focused row with the keyboard.

### Cancelable `row-move`

```ts
// RowDragDropCancelableEventDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/row-drag-drop';

const container = document.getElementById('row-drag-drop-cancelable-event-demo');
if (container) {
  const sampleData = [
    { id: 1, name: 'Alice', department: 'Engineering', email: 'alice@example.com', priority: 1 },
    { id: 2, name: 'Bob', department: 'Marketing', email: 'bob@example.com', priority: 2 },
    { id: 3, name: 'Carol', department: 'Engineering', email: 'carol@example.com', priority: 3 },
    { id: 4, name: 'David', department: 'Sales', email: 'david@example.com', priority: 4 },
    { id: 5, name: 'Eve', department: 'Engineering', email: 'eve@example.com', priority: 5 },
  ];
  const columns = [
    { field: 'priority', header: '#', type: 'number', width: 50 },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
    { field: 'email', header: 'Email' },
  ];

  const status = document.getElementById('row-drag-drop-cancelable-status')!;

  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns,
    features: { rowDragDrop: true },
  };
  grid.rows = sampleData;

  // Prevent moving Bob
  grid.on('row-move', (detail, e) => {
    if (detail.row.name === 'Bob') {
      e.preventDefault();
      status.textContent = '❌ Cannot move Bob!';
      status.style.background = 'var(--tbw-color-danger-light)';
    } else {
      status.textContent = `✓ Moved ${detail.row.name} from index ${detail.fromIndex} to ${detail.toIndex}`;
      status.style.background = 'var(--tbw-color-success-light)';
    }
  });
}
```

Cancel row moves by calling `event.preventDefault()` in the `row-move`
handler.

### Cross-grid transfer

The grids below share `dropZone: 'employees'` with `operation: 'move'`.
Drag any row from the left grid to the right grid (or back).

```ts
// RowDragDropCrossGridDemo.astro
import '@toolbox-web/grid';
import { queryGrid, type ColumnConfig } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/row-drag-drop';
import '@toolbox-web/grid/features/selection';

const container = document.getElementById('row-drag-drop-cross-grid-demo');
if (container) {
  const columns: ColumnConfig<any>[] = [
    { field: 'id', header: 'ID', type: 'number', width: 60 },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
  ];

  const source = queryGrid('tbw-grid#rdd-source', container)!;
  const target = queryGrid('tbw-grid#rdd-target', container)!;

  // Enable Selection on the source grid so multi-row drag is automatic when
  // the dragged row is part of a multi-row selection. RowDragDrop has no
  // `selection` config — the behaviour is driven entirely by the presence of
  // a multi-row selection at dragstart.
  source.gridConfig = {
    columns,
    features: {
      rowDragDrop: { dropZone: 'employees', operation: 'move' },
      selection: 'row',
    },
  };
  source.rows = [
    { id: 1, name: 'Alice', department: 'Engineering' },
    { id: 2, name: 'Bob', department: 'Marketing' },
    { id: 3, name: 'Carol', department: 'Engineering' },
    { id: 4, name: 'David', department: 'Sales' },
    { id: 5, name: 'Eve', department: 'Engineering' },
  ];

  target.gridConfig = {
    columns,
    features: { rowDragDrop: { dropZone: 'employees', operation: 'move' } },
  };
  target.rows = [];
}
```

### Cross-window transfer

Grids in different browser windows (or tabs) on the same origin can also
exchange rows. The button in the demo below opens a popout window that
hosts a target grid joined to the same `dropZone`. Drag any row from the
left grid into the popout — the row is moved across windows, and the
source grid's `row-transfer` event fires once the popout confirms the drop.

```ts
// RowDragDropCrossWindowDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/row-drag-drop';

const container = document.getElementById('row-drag-drop-cross-window-demo');
if (container) {
  const source = queryGrid('tbw-grid#rdd-cross-window-source', container)!;
  const status = container.querySelector('#rdd-cross-window-status') as HTMLElement;
  const btn = container.querySelector('#rdd-popout-btn') as HTMLButtonElement;

  source.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 60 },
      { field: 'name', header: 'Name' },
      { field: 'department', header: 'Department' },
    ],
    features: {
      rowDragDrop: { dropZone: 'cross-window-employees', operation: 'move' },
    },
  };
  source.rows = [
    { id: 1, name: 'Alice', department: 'Engineering' },
    { id: 2, name: 'Bob', department: 'Marketing' },
    { id: 3, name: 'Carol', department: 'Engineering' },
    { id: 4, name: 'David', department: 'Sales' },
    { id: 5, name: 'Eve', department: 'Engineering' },
  ];

  source.addEventListener('row-transfer', ((e: Event) => {
    const detail = (e as CustomEvent).detail as { rows: { name: string }[]; toGridId: string };
    status.textContent = `Sent ${detail.rows.length} row(s) to ${detail.toGridId}.`;
  }) as EventListener);

  btn.addEventListener('click', () => {
    const w = window.open(
      '/grid/row-drag-drop-popout/',
      'tbw-rdd-popout',
      'width=520,height=480,resizable=yes,scrollbars=yes',
    );
    if (!w) {
      status.textContent = 'Popup blocked. Please allow popups for this site and try again.';
    } else {
      status.textContent = 'Popout opened. Drag rows from above into the new window.';
    }
  });
}
```

The popout page itself is a tiny standalone host that registers the same
`dropZone` ([`pages/grid/row-drag-drop-popout.astro`](https://github.com/OysteinAmundsen/toolbox/blob/main/apps/docs/src/pages/grid/row-drag-drop-popout.astro)).

Under the hood the plugin sets a custom MIME type on `dataTransfer` and
opens a `BroadcastChannel('tbw-row-drag-drop')`. The target window decodes
the payload from `dataTransfer` and broadcasts a confirmation; the source
window's plugin instance listens on the same channel and — on `move` —
removes the transferred rows and emits `row-transfer` locally.

**Custom row shapes.** Rows are round-tripped through `JSON.parse(JSON.stringify(row))`
by default. If your rows contain non-JSON values (functions, `Date`, `Map`,
etc.), provide `serializeRow` / `deserializeRow` so the target reconstructs
an equivalent object:

```ts
features: {
  rowDragDrop: {
    dropZone: 'employees',
    serializeRow: (row) => ({ ...row, hiredAt: row.hiredAt.toISOString() }),
    deserializeRow: (raw) => ({ ...raw, hiredAt: new Date(raw.hiredAt) }),
  },
}
```

**Caveats.**

- Cross-window coordination requires `BroadcastChannel`; in environments
  without it (very old browsers, sandboxed iframes), only the target
  receives rows and the source is left untouched.
- Both windows must be on the same origin — `BroadcastChannel` is
  origin-scoped.
- The source's `row-drag-end` may fire with `accepted: false` before the
  remote confirmation arrives. Treat the `row-transfer` event as the
  authoritative success signal for cross-window transfers.

## Configuration

See [`RowDragDropConfig`](./Interfaces/RowDragDropConfig/) for the full list
of options and defaults. Key options:

| Option              | Type                                              | Description                                                                          |
| ------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `dropZone`          | `string`                                          | Opt-in identifier for cross-grid drops. Grids with the same value accept each other. |
| `operation`         | `'move' \| 'copy'`                                | Whether the source grid keeps the rows after a successful cross-grid drop.           |
| `canDrop`           | `(payload, targetIndex) => boolean`               | Reject specific drops on the target grid. Called synchronously during `dragover` and at drop time. |
| `canDrag`           | `(row, index) => boolean`                         | Reject drags from the source. Called once at `dragstart` with the originating row.   |
| `serializeRow`      | `(row) => unknown`                                | Override the JSON shape used in the cross-window fallback payload.                   |
| `deserializeRow`    | `(serialized) => row`                             | Inverse of `serializeRow`.                                                           |
| `enableKeyboard`    | `boolean`                                         | Keep keyboard reorder (`Ctrl + ↑/↓`) — defaults to `true`.                           |
| `dragFrom`          | `'handle' \| 'row' \| 'both'`                     | Where a drag can be initiated. `'handle'` (default) keeps the handle column; `'row'` hides the handle and lets users drag anywhere on the row; `'both'` allows either. Interactive descendants (`button`, `input`, `select`, `textarea`, `a[href]`, `[contenteditable]`) never start a drag. |
| `showDragHandle`    | `boolean`                                         | Render the drag-handle column. Defaults to `true` for `dragFrom: 'handle' \| 'both'` and `false` for `dragFrom: 'row'`. Set explicitly to override.            |
| `dragHandlePosition`| `'left' \| 'right'`                               | Pin the handle column to either side.                                                |
| `dragHandleWidth`   | `number`                                          | Pixel width of the handle column.                                                    |
| `animation`         | `'flip' \| false`                                 | FLIP animation on intra-grid reorder.                                                |
| `autoScroll`        | `boolean \| { edgeSize?: number; speed?: number; maxSpeed?: number }` | Tune the auto-scroll behaviour during drag.                          |

## Events

| Event             | Detail                                                              | Cancelable | When                                                          |
| ----------------- | ------------------------------------------------------------------- | ---------- | ------------------------------------------------------------- |
| `row-move`        | [`RowMoveDetail`](./Interfaces/RowMoveDetail/)                      | Yes        | Intra-grid reorder committed (back-compat).                   |
| `row-drag-start`  | [`RowDragStartDetail`](./Interfaces/RowDragStartDetail/)            | Yes        | A drag begins.                                                |
| `row-drag-end`    | [`RowDragEndDetail`](./Interfaces/RowDragEndDetail/)                | No         | The drag ends, regardless of whether a drop succeeded.        |
| `row-drop`        | [`RowDropDetail`](./Interfaces/RowDropDetail/)                      | Yes        | Rows are dropped on this grid from another grid.              |
| `row-transfer`    | [`RowTransferDetail`](./Interfaces/RowTransferDetail/)              | No         | Successful cross-grid transfer (fired on **both** grids).     |

## Keyboard Shortcuts

| Key          | Action                    |
| ------------ | ------------------------- |
| `Ctrl + ↑`   | Move focused row up       |
| `Ctrl + ↓`   | Move focused row down     |

## Styling

The plugin adds these CSS classes you can customise:

| Class                                  | Description                                         |
| -------------------------------------- | --------------------------------------------------- |
| `.dg-row-drag-handle`                  | The drag handle element                             |
| `.dg-row-drag-handle:hover`            | Handle hover state                                  |
| `.data-grid-row.dragging`              | Row currently being dragged                         |
| `.data-grid-row.drop-target`           | Row being hovered as drop target                    |
| `.data-grid-row.drop-before`           | Drop indicator showing insertion above              |
| `.data-grid-row.drop-after`            | Drop indicator showing insertion below              |
| `.tbw-grid--drag-source`               | The source grid during a drag (whole-grid state)    |
| `.tbw-grid--drop-target-active`        | The target grid during a valid dragover             |
| `.tbw-grid--drop-target-rejected`      | The target grid during a `canDrop`-rejected drag    |
| `.tbw-grid--auto-scrolling`            | A grid currently auto-scrolling during a drag       |

### Custom Handle Icon

Override the default grip icon via CSS:

```css
.dg-row-drag-handle::before {
  content: '⋮⋮'; /* Double vertical ellipsis */
}
```

## Notes

- **Row identification** — currently uses processed/visual row indices
  (`data-row` attribute and `payload.rowIndices`), not `getRowId()`.
  Same-window cross-grid drops also recover live object references via the
  internal `WeakRef` registry; primitive row values fall through to the
  JSON payload.
- **Data mutation** — the plugin reorders `grid.rows` in place. The
  `row-move` event provides the updated array.
- **Virtualization** — works with virtualized grids; only visible rows are
  rendered but logical indices are preserved.
- **Keyboard debounce** — rapid keyboard moves are debounced (150 ms) to
  prevent excessive rerenders.
- **Drag image** — when a drag starts the plugin clones the source row and
  uses it as the HTML5 drag image so the user sees the full row content
  follow the cursor (instead of just the handle cell). The browser applies
  its standard translucency to the snapshot — this is a native effect that
  cannot be disabled.
- **Cross-window fallback** — when the live row reference cannot be
  recovered from the same-window registry (e.g. drop into a different
  window), the row payload is decoded from `dataTransfer` JSON via
  `serializeRow`/`deserializeRow`. The source window completes its half
  of the transfer (row removal on `move`, `row-transfer` emit) when it
  receives the confirmation message on the `tbw-row-drag-drop`
  `BroadcastChannel`.

## Migration from `RowReorderPlugin`

`RowReorderPlugin` is now an alias for `RowDragDropPlugin`. Existing code
keeps working until V3 — both `reorderRows` and `rowDragDrop` feature keys
resolve to the same plugin instance, and merging conflicting configs across
the two keys will throw at attach time. To migrate:

```diff
- import { RowReorderPlugin } from '@toolbox-web/grid/plugins/reorder-rows';
+ import { RowDragDropPlugin } from '@toolbox-web/grid/plugins/row-drag-drop';

- new RowReorderPlugin(cfg);
+ new RowDragDropPlugin(cfg);
```

The legacy `canMove` callback continues to work — it is mapped internally to
`canDrop` with a synthesised intra-grid payload.

## See Also

- **[Column Reorder](../reorder-columns/)** — Drag-to-reorder columns
- **[Selection](../selection/)** — Row and cell selection (drives multi-row drag)

---

# Selection Plugin

> Cell, row, and range selection with full keyboard support, conditional selection, and checkbox mode.

The Selection plugin adds cell, row, and range selection capabilities to the grid with full keyboard support. Whether you need simple cell highlighting or complex multi-range selections, this plugin has you covered.

## Do you actually need this plugin?

The Selection plugin exists to maintain a **selection state** — a set of cells, rows, or ranges — that other plugins can act on. It is the prerequisite for things like:

- [ClipboardPlugin](/grid/plugins/clipboard.md) — copy/paste the current selection
- [ExportPlugin](/grid/plugins/export.md) — when `onlySelected: true`, export only the rows the user has selected (without it, all rows are exported)
- [ContextMenuPlugin](/grid/plugins/context-menu.md) — when present, the context menu will operate on the **multi-row** selection instead of just the right-clicked row (the menu itself works fine without it)
- Any custom logic that needs to know "which rows/cells did the user pick?"

If all you want is to **visually highlight the row the user has navigated to** (the focused row), you do **not** need this plugin. The grid core already tracks keyboard focus on the active cell via the `.cell-focus` class — you can style the surrounding row with a small CSS snippet:

```css
/* Highlight the row containing the focused cell, no plugin required */
tbw-grid .data-grid-row:has(.cell-focus) {
  background-color: var(--tbw-focus-background, rgba(from var(--tbw-color-accent) r g b / 12%));
}

/* Optional: paint the focus tint over sticky/pinned cells too,
   which otherwise have an opaque background to mask scrolling content */
tbw-grid .data-grid-row:has(.cell-focus) > .cell.sticky-left,
tbw-grid .data-grid-row:has(.cell-focus) > .cell.sticky-right {
  background:
    linear-gradient(var(--tbw-focus-background, rgba(from var(--tbw-color-accent) r g b / 12%)) 0 0),
    var(--tbw-color-panel-bg);
}

/* Optional: suppress the per-cell focus outline if you want a row-only
   indicator. The grid core paints `outline: var(--tbw-focus-outline)` on
   `.cell-focus` while the grid has focus; leaving it ON makes it easier
   for keyboard users to see which cell they're on inside the highlighted
   row. Only add this rule if you specifically want the row to be the sole
   focus indicator (mimicking the Selection plugin's row mode).

   The grid core sets the `data-has-focus` attribute on the host element
   whenever focus is inside the grid (managed by the focus controller),
   and removes it on blur — so this rule only suppresses the cell outline
   while the grid is actively focused. */
tbw-grid[data-has-focus] .cell-focus {
  outline: none;
}
```

This mirrors what the Selection plugin does for `row` mode focus — without shipping the plugin's selection-state machinery, keyboard range extension, or click handlers. Reach for the plugin only when something downstream needs to read or react to a selection.

## Installation

```ts
import '@toolbox-web/grid/features/selection';
```

## Basic Usage

#### Angular

  ```typescript
  import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
  import { Component } from '@angular/core';
  import { Grid } from '@toolbox-web/grid-angular';
  import type { ColumnConfig } from '@toolbox-web/grid';

  @Component({
    selector: 'app-my-grid',
    imports: [Grid, GridSelectionDirective],
    template: `
      <tbw-grid
        [rows]="rows"
        [columns]="columns"
        [selection]="'row'"
        style="height: 400px; display: block;">
      </tbw-grid>
    `,
  })
  export class MyGridComponent {
    rows = [
      { id: 1, name: 'Alice', email: 'alice@example.com' },
      { id: 2, name: 'Bob', email: 'bob@example.com' },
    ];
    columns: ColumnConfig[] = [
      { field: 'id', header: 'ID' },
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
    ];
  }
  ```

## Interactive Demo

Switch between selection modes to see how each one behaves. The state panel below the grid shows the current selection in real time.

- **Cell mode:** Click cells to select them individually
- **Row mode:** Click anywhere in a row to select the entire row. Ctrl+Click to toggle, Shift+Click for range
- **Range mode:** Click and drag to select rectangular ranges. Ctrl+drag for multiple ranges
- **Column mode:** Ctrl/⌘+Click on a header (or Ctrl/⌘+Space on a focused cell) selects that column. Ctrl+Shift+Click extends from the column anchor.

```ts
// SelectionPlaygroundDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/selection';

  const container = document.getElementById('playground-selection-demo');
  if (container) {
    const grid = queryGrid('tbw-grid', container);
    const output = container.querySelector<HTMLElement>('[data-output-id="selection-demo"]');

    if (grid) {
      const sampleData = [
        { id: 1, name: 'Alice', department: 'Engineering', salary: 95000, email: 'alice@example.com' },
        { id: 2, name: 'Bob', department: 'Marketing', salary: 75000, email: 'bob@example.com' },
        { id: 3, name: 'Carol', department: 'Engineering', salary: 105000, email: 'carol@example.com' },
        { id: 4, name: 'Dan', department: 'Sales', salary: 85000, email: 'dan@example.com' },
        { id: 5, name: 'Eve', department: 'Marketing', salary: 72000, email: 'eve@example.com' },
        { id: 6, name: 'Frank', department: 'Engineering', salary: 98000, email: 'frank@example.com' },
        { id: 7, name: 'Grace', department: 'Sales', salary: 88000, email: 'grace@example.com' },
        { id: 8, name: 'Henry', department: 'HR', salary: 65000, email: 'henry@example.com' },
      ];

      const columns = [
        { field: 'id', header: 'ID', type: 'number' as const },
        { field: 'name', header: 'Name' },
        { field: 'department', header: 'Department' },
        { field: 'salary', header: 'Salary', type: 'number' as const },
        { field: 'email', header: 'Email' },
      ];

      function setupGrid(mode: string) {
        const selectionMode: any = mode === 'row+column' ? ['row', 'column'] : mode;
        grid.gridConfig = { columns, features: { selection: { mode: selectionMode } } };
        grid.rows = sampleData;

        grid.on('selection-change', () => {
          const plugin = grid.getPluginByName('selection');
          if (!plugin || !output) return;
          const sel: any = plugin.getSelection();
          const modeLabel = Array.isArray(sel.mode) ? '[' + sel.mode.join(', ') + ']' : sel.mode;
          const lines = ['<b>mode:</b> ' + modeLabel, '<b>activeAxis:</b> ' + sel.activeAxis];

          if (sel.activeAxis === 'column') {
            const cols = plugin.getSelectedColumns();
            lines.push('<b>selectedColumns:</b> [' + cols.map((c: string) => '"' + c + '"').join(', ') + ']');
          }

          if (sel.activeAxis === 'row') {
            const indices = plugin.getSelectedRowIndices();
            lines.push('<b>selectedRows:</b> [' + indices.join(', ') + ']');
            if (indices.length > 0) {
              const names = indices.map((i: number) => sampleData[i]?.name).filter(Boolean);
              lines.push('<b>rowData:</b> ' + names.map((n: string) => '"' + n + '"').join(', '));
            }
          }

          if (sel.ranges.length > 0) {
            const rangeStrs = sel.ranges.map(
              (r: { from: { row: number; col: number }; to: { row: number; col: number } }) =>
                '{ from: {row:' + r.from.row + ', col:' + r.from.col + '}, to: {row:' + r.to.row + ', col:' + r.to.col + '} }'
            );
            lines.push('<b>ranges:</b> [' + rangeStrs.join(', ') + ']');
            if (sel.mode === 'range') {
              lines.push('<b>cellCount:</b> ' + plugin.getSelectedCells().length);
            }
          } else {
            lines.push('<b>ranges:</b> []');
          }

          output.innerHTML = lines.join('<br>');
        });
      }

      setupGrid('cell');

      container.addEventListener('control-change', ((e: CustomEvent) => {
        setupGrid(e.detail.allValues.mode as string);
      }) as EventListener);
    }
  }
```

### Checkbox Selection

Add `checkbox: true` to show a selection checkbox column with a "select all" header. Works exclusively in row mode.

```ts
// SelectionCheckboxDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/selection';

  const container = document.getElementById('checkbox-selection-demo');
  if (container) {
    const grid = queryGrid('tbw-grid', container);
    if (grid) {
      grid.gridConfig = {
        columns: [
          { field: 'id', header: 'ID', type: 'number' as const },
          { field: 'name', header: 'Name' },
          { field: 'department', header: 'Department' },
          { field: 'salary', header: 'Salary', type: 'number' as const },
        ],
        features: { selection: { mode: 'row', checkbox: true } },
      };
      grid.rows = [
        { id: 1, name: 'Alice', department: 'Engineering', salary: 95000 },
        { id: 2, name: 'Bob', department: 'Marketing', salary: 75000 },
        { id: 3, name: 'Carol', department: 'Engineering', salary: 105000 },
        { id: 4, name: 'Dan', department: 'Sales', salary: 85000 },
        { id: 5, name: 'Eve', department: 'Marketing', salary: 72000 },
      ];
    }
  }
```

```ts
features: { selection: { mode: 'row', checkbox: true } }
```

### Column Selection

(Since 2.8.0)

Set `mode: 'column'` to enable column-axis selection. Selected columns are tracked by **field name** (not visible-index), so the selection survives column pinning, reordering, virtualization recycling, and visibility changes.

```ts
features: { selection: { mode: 'column' } }
```

You can combine column selection with one in-row axis (`'cell'`, `'row'`, or `'range'`) by passing an array. The two axes are **mutually exclusive** at any given moment — selecting on one clears the other and announces the axis change to assistive technology:

```ts
features: { selection: { mode: ['row', 'column'] } }
```

Invalid combinations (`['cell', 'row']`, `['cell', 'range']`, `['row', 'range']`) throw at attach time — only `'column' + X` array shapes are accepted.

**Activation paths**

| Input | Action |
| ----- | ------ |
| `Ctrl/⌘ + Click` on column header | Toggle column |
| `Ctrl/⌘ + Shift + Click` on column header | Extend from anchor |
| `Ctrl/⌘ + Space` | Toggle column at focused cell |
| `Ctrl/⌘ + Shift + ←/→` | Extend column selection |
| Plain header click | Reserved for sort (no selection change) |

Utility columns (checkbox, expander, etc.) are never selectable. With `multiSelect: false`, only one column can be selected at a time and `selectAllColumns()` is a no-op.

## Configuration Options

### Grid-Level Toggle

You can disable selection grid-wide using `gridConfig.selectable`:

```ts
grid.gridConfig = {
  selectable: false, // Disables ALL selection
  features: { selection: 'range' },
};
```

### Plugin Options

See [`SelectionConfig`](./Interfaces/SelectionConfig/) for the full list of options and defaults.

### Double-Click Selection Trigger

In data-entry grids, you may want single-click to only **focus** the row/cell for keyboard navigation, while **double-click** changes the selection state.

:::note
`triggerOn` only applies to `'cell'` and `'row'` modes. Range mode uses drag selection (mousedown → mousemove), which is unaffected.
:::

```ts
features: {
  selection: {
    mode: 'row',
    triggerOn: 'dblclick',  // Single-click focuses, double-click selects
  },
}
```

### Conditional Selection

Use the `isSelectable` callback to prevent selection of specific rows or cells:

```ts
features: {
  selection: {
    mode: 'row',
    isSelectable: (row) => row.status !== 'locked',
  },
}
```

**Behavior of non-selectable rows/cells:**

| Aspect | Behavior |
|--------|----------|
| Click | Ignored (no selection change) |
| Keyboard | Skipped with Shift+Arrow |
| Select All | Excluded |
| Visual | Muted via `[data-selectable="false"]` attribute |
| Focus | Still navigable |

```ts
// ConditionalSelectionDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/selection';

  const grid = queryGrid('#demo-conditional-selection');
  if (grid) {
    grid.gridConfig = {
      columns: [
        { field: 'id', header: 'ID', type: 'number', width: 80 },
        { field: 'name', header: 'Name' },
        { field: 'department', header: 'Department' },
        { field: 'status', header: 'Status' },
      ],
      features: {
        selection: {
          mode: 'row',
          isSelectable: (row: { status: string }) => row.status !== 'locked',
        },
      },
    };

    grid.rows = [
      { id: 1, name: 'Alice Johnson', department: 'Engineering', status: 'active' },
      { id: 2, name: 'Bob Smith', department: 'Marketing', status: 'locked' },
      { id: 3, name: 'Carol Davis', department: 'Engineering', status: 'active' },
      { id: 4, name: 'Dan Wilson', department: 'Sales', status: 'locked' },
      { id: 5, name: 'Eve Brown', department: 'HR', status: 'active' },
      { id: 6, name: 'Frank Miller', department: 'Engineering', status: 'active' },
      { id: 7, name: 'Grace Lee', department: 'Finance', status: 'locked' },
      { id: 8, name: 'Hank Taylor', department: 'Sales', status: 'active' },
    ];
  }
```

## Keyboard Shortcuts

| Shortcut | Action |
| -------- | ------ |
| `Arrow Keys` | Move focus |
| `Shift + Arrow` | Extend selection (row and range modes) |
| `Shift + Page Up/Down` | Extend selection by page (row and range modes) |
| `Shift + Ctrl/⌘ + Home/End` | Extend selection to first/last row (row and range modes) |
| `Ctrl/⌘ + Click` | Toggle row/cell (multi-select) |
| `Shift + Click` | Extend selection from anchor |
| `Ctrl/⌘ + A` | Select all (row and range modes) |
| `Ctrl/⌘ + Click` (header) | Toggle column selection (column mode) |
| `Ctrl/⌘ + Shift + Click` (header) | Extend column selection from anchor |
| `Ctrl/⌘ + Space` | Toggle column at the focused column (column mode) |
| `Ctrl/⌘ + Shift + ←/→` | Extend column selection (column mode) |
| `Escape` | Clear current selection (whichever axis is active) |

## Programmatic API

```ts
const plugin = grid.getPluginByName('selection');

// Query
const selection = plugin.getSelection();
plugin.isCellSelected(2, 1);

// Row mode
plugin.selectRows([0, 2, 4]);
const rows = plugin.getSelectedRows<Employee>();

// Range mode
plugin.setRanges([{ from: { row: 0, col: 0 }, to: { row: 5, col: 3 } }]);

// Column mode (since 2.8.0)
plugin.selectColumn('email');
plugin.selectColumn('name', { toggle: true });
plugin.selectColumn('lastLogin', { range: true }); // From column anchor
plugin.deselectColumn('email');
plugin.selectAllColumns();
plugin.clearColumnSelection();
const cols = plugin.getSelectedColumns(); // string[]

// Actions
plugin.selectAll();
plugin.clearSelection();
```

:::tip
Use `getSelectedRows()` to retrieve actual row data objects rather than resolving indices manually. Row indices refer to positions in the grid's current (sorted/filtered) row array, which may differ from your original data array.
:::

## Events

| Event | Description |
| ----- | ----------- |
| `selection-change` | Fired when the selection is modified |

```ts
// SelectionEventsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';

import '@toolbox-web/grid/features/selection';

const container = document.getElementById('selection-events-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);
  const logEl = container.querySelector('#selection-events-log')!;
  const clearBtn = container.querySelector('#selection-events-clear-btn');

  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number', width: 60 },
      { field: 'name', header: 'Name' },
      { field: 'department', header: 'Department' },
      { field: 'salary', header: 'Salary', type: 'number', align: 'right' },
    ],
    features: { selection: 'range' },
  };

  grid.rows = [
    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 85000 },
    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 72000 },
    { id: 3, name: 'Carol White', department: 'Sales', salary: 68000 },
    { id: 4, name: 'David Brown', department: 'Engineering', salary: 92000 },
    { id: 5, name: 'Eve Davis', department: 'HR', salary: 65000 },
  ];

  function addLog(msg: string) {
    const entry = document.createElement('div');
    entry.className = 'event-log-entry';
    entry.textContent = `[${new Date().toLocaleTimeString()}] ${msg}`;
    logEl.prepend(entry);
  }

  grid.on('selection-change', (detail) => {
    addLog(`selection-change — ${detail.selectedCount ?? 0} cell(s) selected`);
  });

  grid.on('row-select', (detail) => {
    addLog(`row-select — row ${detail.rowIndex}`);
  });

  clearBtn?.addEventListener('click', () => {
    logEl.innerHTML = '';
  });
}
```

### `selection-change` Detail

See [`SelectionChangeDetail`](./Interfaces/SelectionChangeDetail/) and [`CellRange`](./Interfaces/CellRange/) for the full event payload types.

## Styling

:::tip
If you only want a focused-row highlight and don't need the selection state, see [Do you actually need this plugin?](#do-you-actually-need-this-plugin) for a CSS-only recipe that mimics the row-focus look.
:::

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-focus-background` | `rgba(accent, 12%)` | Focused row background |
| `--tbw-range-selection-bg` | `rgba(accent, 12%)` | Range selection fill |
| `--tbw-range-border-color` | `var(--tbw-color-accent)` | Range selection border |
| `--tbw-color-accent` | `#3b82f6` | Primary accent color |

```css
tbw-grid {
  --tbw-range-selection-bg: rgba(76, 175, 80, 0.15);
  --tbw-range-border-color: #4caf50;
  --tbw-focus-background: rgba(76, 175, 80, 0.1);
}
```

### CSS Classes

| Class | Element |
| --- | --- |
| `.selecting` | Grid during range drag |
| `.row-focus` | Focused row (row mode) |
| `.cell-focus` | Focused cell (cell mode) |
| `.selected` | Selected cell in range |
| `.selected.top` / `.bottom` / `.first` / `.last` | Range boundary edges |

## Works Well With

| Plugin | Integration |
|--------|-------------|
| [EditingPlugin](/grid/plugins/editing.md) | Click-to-select + double-click-to-edit. In `mode: 'row'` the row entering edit is auto-added to the selection so `getSelectedRows()` always reflects the row the user is visibly editing. With `multiSelect: false` the selection is replaced; otherwise the edited row is added to the existing set. Selection is also automatically cleared when the host replaces the `rows` array with a different number of source rows, preventing stale indices from pointing at the wrong rows. |
| [ClipboardPlugin](/grid/plugins/clipboard.md) | Copy/paste selected cells (requires SelectionPlugin) |
| [FilteringPlugin](/grid/plugins/filtering.md) | Filter data, then select from results |
| [ContextMenuPlugin](/grid/plugins/context-menu.md) | Right-click selected rows for actions |

## See Also

- [Common Patterns](/grid/guides/common-patterns.md) — Full application recipes using selection
- [Plugins Overview](/grid/plugins.md) — All available plugins and compatibility
- [Events Reference](/grid/api-reference.md#events) — `selection-change` event details

---

# Server-Side Plugin

> Connect the grid to server-side data sources with virtual scrolling.

The Server-Side plugin enables **virtual scrolling with lazy loading** from a remote API. It's designed for large datasets (10,000+ rows) where loading all data upfront would be impractical or slow.

## When to Use This Plugin

| Scenario | Recommended Approach |
|----------|---------------------|
| < 1,000 rows | Load all data upfront (no plugin needed) |
| 1,000 - 10,000 rows | Consider based on network speed and data complexity |
| 10,000+ rows | **Use ServerSidePlugin** |
| Infinite scroll / pagination | **Use ServerSidePlugin** |
| Data changes frequently on server | **Use ServerSidePlugin** with `refresh()` |

## Key Features

- **Block-based fetching**: Loads only visible rows plus a buffer
- **LRU caching**: Keeps recently viewed blocks in memory
- **Automatic prefetching**: Loads next blocks as user scrolls
- **Concurrent request limiting**: Prevents overwhelming the server
- **Loading placeholders**: Shows loading state for pending rows
- **Integration with sorting/filtering**: Works with `sortHandler` and `filterHandler`

## Installation

```ts
import '@toolbox-web/grid/features/server-side';
```

## Basic Usage

The feature requires a **data source** that implements the `getRows` method. Pass it directly in the config via `dataSource`:

#### Angular

```typescript
// Feature import - enables the [serverSide] input
import { GridServerSideDirective } from '@toolbox-web/grid-angular/features/server-side';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';
import type { GetRowsParams, ServerSideDataSource } from '@toolbox-web/grid/plugins/server-side';

@Component({
  selector: 'app-server-side-grid',
  imports: [Grid, GridServerSideDirective],
  template: `
    <tbw-grid
      [columns]="columns"
      [serverSide]="serverSideConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class ServerSideGridComponent {
  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ];

  dataSource: ServerSideDataSource = {
    getRows: async (params: GetRowsParams) => {
      const response = await fetch(`/api/data?start=${params.startNode}&end=${params.endNode}`);
      const data = await response.json();
      return { rows: data.rows, totalNodeCount: data.total };
    },
  };

  serverSideConfig = {
    pageSize: 50,
    dataSource: this.dataSource,
  };
}
```

## Declarative `data-src` (zero-JS)

For the simplest case — render a server-fetched grid from static HTML with no
JavaScript — set a `data-src` attribute on the `<tbw-grid>` host. When the plugin
attaches and no JS `dataSource` is configured, it fetches the whole dataset from that
URL once and serves it to the grid in blocks:

```html
<tbw-grid grid-config='{"features":{"serverSide":true}}' data-src="/api/rows.json"></tbw-grid>
```

The endpoint may return either a plain array of rows or a `{ rows, totalNodeCount }`
envelope:

```jsonc
// Plain array — totalNodeCount derived from length
[{ "id": 1, "name": "Alice" }, { "id": 2, "name": "Bob" }]

// Envelope — totalNodeCount honoured
{ "rows": [{ "id": 1, "name": "Alice" }], "totalNodeCount": 5000 }
```

:::note
`data-src` is read **once at attach time** and fetches the entire dataset (it caches
the result and slices it per block). A JS `dataSource` always takes precedence. For
true server-side pagination, remote sort/filter, or per-block fetching, provide a
`dataSource` callback as shown above instead.

`data-src` is primarily a zero-JS/vanilla convenience. In React, Vue, and Angular,
prefer adapter-native setup with `gridConfig.features.serverSide` and framework-native
renderers/editors.
:::

## Demo

Toggle between virtual scrolling and paging mode, adjust the page size, and enable server-side sorting — all in one demo.

```ts
// ServerSideDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/filtering';
import '@toolbox-web/grid/features/pinned-rows';
import '@toolbox-web/grid/features/server-side';

const container = document.getElementById('server-side-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container)!;
  const pager = container.querySelector('.pager') as HTMLElement;
  const prevBtn = pager.querySelector('.prev') as HTMLButtonElement;
  const nextBtn = pager.querySelector('.next') as HTMLButtonElement;
  const pageInfo = pager.querySelector('.page-info') as HTMLSpanElement;

  const columns = [
    { field: 'id', header: 'ID', type: 'number', sortable: true, filterable: false },
    { field: 'name', header: 'Name', sortable: true },
    { field: 'department', header: 'Department', sortable: true },
    { field: 'salary', header: 'Salary', type: 'number', sortable: true },
    { field: 'email', header: 'Email' },
  ];

  const departments = ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'];
  const allData = Array.from({ length: 10000 }, (_, i) => ({
    id: i + 1,
    name: `Employee ${i + 1}`,
    department: departments[i % departments.length],
    salary: 50000 + Math.floor(Math.random() * 50000),
    email: `employee${i + 1}@example.com`,
  }));

  let currentPage = 0;
  let currentPageSize = 50;
  let pageData = allData; // sorted/filtered view used by paging mode
  let pageSortModel: { field: string; direction: 'asc' | 'desc' } | null = null;
  let pageFilterModel: Record<string, any> | undefined;
  // In-flight getRows count. Used by the right-side custom panel to switch
  // between "Scroll to load more rows..." and "Loading..." messages.
  let loadingCount = 0;

  function refreshPinnedRows() {
    grid.getPluginByName('pinnedRows')?.refresh?.();
  }

  function sortData(data: typeof allData, sort: { field: string; direction: 'asc' | 'desc' }) {
    const dir = sort.direction === 'asc' ? 1 : -1;
    return [...data].sort((a, b) => {
      const aVal = (a as Record<string, unknown>)[sort.field];
      const bVal = (b as Record<string, unknown>)[sort.field];
      const cmp = aVal! < bVal! ? -1 : aVal! > bVal! ? 1 : 0;
      return cmp * dir;
    });
  }

  function applyFilters(data: typeof allData, filterModel: Record<string, any> | undefined) {
    if (!filterModel) return data;
    const fields = Object.keys(filterModel);
    if (fields.length === 0) return data;
    return data.filter((row) =>
      fields.every((field) => {
        const f = filterModel[field];
        if (!f) return true;
        const val = (row as Record<string, unknown>)[field];
        // Set filter: { value: string[] } — keep rows whose value is in the set.
        if (Array.isArray(f.value)) return f.value.includes(val);
        // Text contains (default for strings)
        if (typeof f.value === 'string') {
          return String(val).toLowerCase().includes(f.value.toLowerCase());
        }
        return true;
      }),
    );
  }

  function createDataSource() {
    return {
      async getRows(params: any) {
        loadingCount++;
        refreshPinnedRows();
        try {
          await new Promise((r) => setTimeout(r, 200));
          let data = allData;
          if (params.filterModel) data = applyFilters(data, params.filterModel);
          if (params.sortModel?.length) data = sortData(data, params.sortModel[0]);
          return { rows: data.slice(params.startNode, params.endNode), totalNodeCount: data.length };
        } finally {
          loadingCount = Math.max(0, loadingCount - 1);
          refreshPinnedRows();
        }
      },
    };
  }

  function recomputePageData() {
    let data = allData;
    if (pageFilterModel) data = applyFilters(data, pageFilterModel);
    if (pageSortModel) data = sortData(data, pageSortModel);
    pageData = data;
  }

  function updatePager() {
    const totalPages = Math.ceil(pageData.length / currentPageSize);
    pageInfo.textContent = `Page ${currentPage + 1} of ${totalPages}`;
    prevBtn.disabled = currentPage === 0;
    nextBtn.disabled = currentPage >= totalPages - 1;
  }

  function loadPage(page: number) {
    currentPage = page;
    grid.rows = pageData.slice(page * currentPageSize, (page + 1) * currentPageSize);
    updatePager();
  }

  function rebuild(values: Record<string, unknown>) {
    const mode = values.mode as string;
    const pageSize = values.pageSize as number;
    const loadThreshold = values.loadThreshold as number;
    const serverSort = values.serverSort as boolean;
    const serverFilter = values.serverFilter as boolean;
    currentPageSize = pageSize;

    const config: any = { columns };

    if (mode === 'virtual') {
      pager.style.display = 'none';
      config.features = {
        // When the corresponding toggle is OFF, sort/filter the already-loaded
        // rows locally (no refetch). When ON, the default 'server' mode triggers
        // a refetch through getRows with sortModel/filterModel.
        serverSide: {
          pageSize,
          loadThreshold,
          sortMode: serverSort ? 'server' : 'local',
          filterMode: serverFilter ? 'server' : 'local',
        },
        filtering: true,
        pinnedRows: {
          position: 'bottom',
          showRowCount: false,
          customPanels: [
            {
              id: 'loaded-count',
              position: 'left',
              render: (ctx: any) => {
                const total = ctx.totalRows;
                const rows = (ctx.grid as any).rows as unknown[] | undefined;
                const loaded = Array.isArray(rows)
                  ? rows.filter((r) => !(r as any)?.__loading).length
                  : 0;
                return loaded >= total ? `Rows: ${total}` : `Rows: ${loaded}/${total}`;
              },
            },
            {
              id: 'scroll-info',
              position: 'right',
              render: (ctx: any) => {
                if (loadingCount > 0) return '<em>Loading...</em>';
                const total = ctx.totalRows;
                const rows = (ctx.grid as any).rows as unknown[] | undefined;
                const loaded = Array.isArray(rows)
                  ? rows.filter((r) => !(r as any)?.__loading).length
                  : 0;
                if (loaded >= total) return '';
                return '<em>Scroll to load more rows...</em>';
              },
            },
          ],
        },
      };
    } else {
      pager.style.display = 'flex';
      currentPage = 0;
      pageSortModel = null;
      pageFilterModel = undefined;
      recomputePageData();
      // Paging mode is a custom code path: the serverSide plugin isn't used,
      // so we wire sort-change/filter-change ourselves and rebuild the page
      // from the full data set. Honors the serverSort/serverFilter toggles by
      // simulating a server round-trip (the local-only branch would only sort
      // the 50 rows already on screen).
      config.features = { filtering: true };
    }

    grid.gridConfig = config;

    if (mode === 'virtual') {
      grid.ready().then(() => grid.getPluginByName('serverSide')?.setDataSource(createDataSource() as any));
    } else {
      // Paging mode wires sort/filter listeners itself. When the toggle is ON
      // ("server"), reslice from the full dataset; when OFF ("local"), let the
      // grid sort/filter just the current page in place (default behavior).
      grid.ready().then(() => {
        if (serverSort) {
          grid.addEventListener('sort-change', ((e: CustomEvent) => {
            const detail = e.detail as { field?: string; direction?: number } | undefined;
            pageSortModel = detail?.field && (detail.direction === 1 || detail.direction === -1)
              ? { field: detail.field, direction: detail.direction === 1 ? 'asc' : 'desc' }
              : null;
            recomputePageData();
            loadPage(0);
          }) as EventListener);
        }
        if (serverFilter) {
          grid.addEventListener('filter-change', (() => {
            const active = grid.getPluginByName('filtering')?.getActiveFilters?.() ?? [];
            pageFilterModel = active.length
              ? Object.fromEntries(active.map((f: any) => [f.field, f]))
              : undefined;
            recomputePageData();
            loadPage(0);
          }) as EventListener);
        }
        loadPage(0);
      });
    }
  }

  rebuild({ mode: 'virtual', pageSize: 50, loadThreshold: 0, serverSort: false, serverFilter: false });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues);
  }) as EventListener);

  prevBtn.addEventListener('click', () => loadPage(currentPage - 1));
  nextBtn.addEventListener('click', () => loadPage(currentPage + 1));
}
```

### Server-Side Sorting & Filtering

The plugin handles sorting and filtering natively: when the user clicks a sortable header or applies a column filter, the cache is purged and `getRows()` is called again with `sortModel` and `filterModel` populated. Your handler decides how to translate those into the request:

```ts
async getRows(params: GetRowsParams) {
  const url = new URL('/api/data', location.origin);
  url.searchParams.set('start', String(params.startNode));
  url.searchParams.set('end', String(params.endNode));
  if (params.sortModel?.length) {
    url.searchParams.set('sort', params.sortModel[0].field);
    url.searchParams.set('dir', params.sortModel[0].direction);
  }
  if (params.filterModel) {
    url.searchParams.set('filter', JSON.stringify(params.filterModel));
  }
  const res = await fetch(url);
  return res.json();
}
```

Toggle **Server-side sorting** / **Server-side filtering** in the demo above to see the request parameters change. Toggling them off switches to [local mode](#local-sort--filter-modes) — the plugin keeps the loaded blocks and sorts/filters them in the browser without a refetch.

:::note[Standalone handlers]
The grid also exposes [`sortHandler`](/grid/plugins/multi-sort.md#server-side-sorting) (core `GridConfig`) and [`filterHandler` / `valuesHandler`](/grid/plugins/filtering.md#server-side-filtering) (FilteringPlugin config). These are **independent** of the ServerSidePlugin and let you offload sort/filter work to the server **without** opting into block-based virtual scrolling. Use them when you want async sort/filter against an already-loaded dataset; use ServerSidePlugin's native `sortModel`/`filterModel` when you want them combined with lazy block loading.
:::

### Local Sort / Filter Modes

By default, the ServerSidePlugin treats every sort or filter change as a model change: it purges the cache and refetches all visible blocks. This is correct when the backend owns ordering and filtering, but if you want to sort or filter the **already-loaded** rows in the browser without a roundtrip, set the corresponding mode to `'local'`:

```ts
serverSide: {
  dataSource,
  sortMode: 'local',   // re-sort cached rows in place; no refetch
  filterMode: 'local', // re-filter cached rows in place; no refetch
}
```

When a mode is `'local'`:

- The plugin no longer refetches on `sort-change` / `filter-change` — it just requests a re-render.
- The corresponding `sortModel` / `filterModel` is **omitted** from `GetRowsParams` so scroll-triggered block fetches don't leak local state to the backend.
- Already-loading placeholder rows are pinned to the end of the sort order so the in-progress fetch stays visually grouped.

| Use case                                      | `sortMode` | `filterMode` |
| --------------------------------------------- | ---------- | ------------ |
| Backend owns sort + filter (default)          | `'server'` | `'server'`   |
| Backend filters; user re-sorts on screen      | `'local'`  | `'server'`   |
| Backend pre-sorts; user filters on screen     | `'server'` | `'local'`    |
| All processing on already-loaded page         | `'local'`  | `'local'`    |

:::caution
Local filtering only filters rows currently in the cache. With virtual scrolling enabled, that's the visible window plus any prefetched blocks — not the full dataset. Use `'local'` filtering only when the loaded subset is meaningful on its own (for example, paged mode).
:::

:::note
A column with a custom `sortComparator` is treated as user-owned: loading placeholder rows are **not** auto-pinned. Pin them yourself in your comparator if you want the same behaviour.
:::

### Prefetching with `loadThreshold`

By default the plugin only fetches a block when the **visible viewport** enters it. On gentle scrolling this means users see placeholder rows for the duration of the network round-trip. Set `loadThreshold` to prefetch the next block(s) before the user scrolls into them:

```ts
serverSide: {
  dataSource,
  pageSize: 100,
  loadThreshold: 50, // start fetching the next block when within 50 rows of it
}
```

The threshold is applied symmetrically (the viewport is expanded by `loadThreshold` rows in both directions before block coverage is computed). The `maxConcurrentRequests` cap and per-block dedup still apply, so a large threshold during fast scrolling will not flood the server.

A reasonable starting point is `pageSize / 2`. Values larger than `pageSize` will eagerly request 2+ blocks ahead, which can hurt perceived performance with slow backends.

### Request Cancellation

`getRows()` may return either a `Promise` or an `Observable` (anything with a `.subscribe()` method — RxJS `Observable`, the TC39 Observable proposal shape, etc.). The plugin cancels superseded requests automatically:

- **Promise / `fetch`** — call `getRows()` receives an `AbortSignal` on `params.signal`. Pass it to `fetch(url, { signal })` and the browser cancels the request:

  ```ts
  async getRows(params) {
    const res = await fetch(`/api/data?start=${params.startNode}&end=${params.endNode}`, {
      signal: params.signal,
    });
    const data = await res.json();
    return { rows: data.items, totalNodeCount: data.total };
  }
  ```

- **Observable / Angular `HttpClient`** — return the observable directly. The plugin subscribes once and calls `unsubscribe()` when the request is superseded; `HttpClient` cancels the underlying XHR in response to that. No `firstValueFrom`, no `takeUntil`, no signal plumbing:

  ```ts
  getRows: (params) =>
    this.http
      .get<EmployeesResponse>('/api/data', { params: toHttpParams(params) })
      .pipe(map((d) => ({ rows: d.items, totalNodeCount: d.total }))),
  ```

A request is considered **superseded** when the sort/filter model changes mid-flight, when `refresh()` or `purgeCache()` is called, or when the plugin detaches. If a data source ignores cancellation entirely, the plugin still discards the late result so a stale block can't overwrite a freshly-loaded one.

## Configuration Options

See [`ServerSideConfig`](./Interfaces/ServerSideConfig/) for the full list of options and defaults.

## TypeScript Interfaces

- [`ServerSideDataSource`](./Interfaces/ServerSideDataSource/) — Data source contract with `getRows()` and optional `getChildRows()`
- [`GetRowsParams`](./Interfaces/GetRowsParams/) — Parameters passed to `getRows()` (startNode, endNode, sortModel, filterModel, signal)
- [`GetRowsResult`](./Interfaces/GetRowsResult/) — Return type with `rows` and `totalNodeCount`
- [`GetChildRowsParams`](./Interfaces/GetChildRowsParams/) — Parameters for `getChildRows()` with plugin context
- [`GetChildRowsResult`](./Interfaces/GetChildRowsResult/) — Return type with `rows`

## Programmatic API

```ts
const plugin = grid.getPluginByName('serverSide');

plugin.setDataSource(newDataSource);  // Replace the data source at runtime
plugin.refresh();                      // Reload current viewport from server
plugin.purgeCache();                   // Clear all cached blocks
plugin.getTotalNodeCount();            // Get server-reported total node count
plugin.isNodeLoaded(index);            // Check if a specific node is in cache
plugin.getLoadedBlockCount();          // Number of blocks currently cached
```

:::tip
For most use cases, pass `dataSource` directly in the config — no need for `setDataSource()`. Use `setDataSource()` only when you need to **swap** the data source at runtime (e.g., switching API endpoints based on user action).
:::

## Architecture: How It Works

The plugin uses a **block-based caching strategy**:

```
┌────────────────────────────────────────────────┐
│  Total Dataset: 100,000 rows (on server)       │
├────────────────────────────────────────────────┤
│  Block 0: rows 0-99     [CACHED]               │
│  Block 1: rows 100-199  [CACHED]               │
│  Block 2: rows 200-299  [LOADING...]           │
│  Block 3: rows 300-399  [NOT LOADED]           │
│  ...                                           │
│  Block 999: rows 99900-99999 [NOT LOADED]      │
└────────────────────────────────────────────────┘
```

**Scroll triggers:**
1. `onScroll` event fires
2. Plugin calculates which blocks are needed for the visible viewport
3. Missing blocks are requested from the data source
4. `requestRender()` is called when data arrives
5. Grid re-renders with new data

**Loading state:**
Rows that haven't loaded yet are represented with placeholder objects:
```ts
{ __loading: true, __index: 42 }
```

You can detect loading rows via a custom cell renderer and style them accordingly:
```ts
columns: [{
  field: 'name',
  renderer: (value, row) => row.__loading ? '<span class="loading">Loading…</span>' : value,
}]
```

:::tip[Framework adapter best practice]
In React/Vue/Angular, prefer adapter-native renderer APIs (JSX renderers, Vue slots/components,
Angular template/component renderers) over plain `HTMLElement`/string renderer functions.
See [Core → Renderers](/grid/core.md#renderers) and [Core → Custom Header Renderers](/grid/core.md#custom-header-renderers).
:::

## Live Data Updates (WebSocket/SSE)

The grid's **Transaction API** lets you push real-time updates from any streaming source — WebSocket, Server-Sent Events, polling, or any other transport — into the grid efficiently.

The grid deliberately does **not** manage transport connections. Your application owns the WebSocket/SSE lifecycle (authentication, reconnection, backoff), and the grid provides the efficient mutation primitives to apply incoming changes.

### WebSocket Example

#### Angular

```typescript
import { GridServerSideDirective } from '@toolbox-web/grid-angular/features/server-side';
import { Component, effect, OnDestroy } from '@angular/core';
import { Grid, injectGrid } from '@toolbox-web/grid-angular';
import type { ColumnConfig, RowTransaction } from '@toolbox-web/grid';
import type { GetRowsParams, ServerSideDataSource } from '@toolbox-web/grid/plugins/server-side';

interface Employee {
  id: string;
  name: string;
  status: string;
}

@Component({
  selector: 'app-live-grid',
  imports: [Grid, GridServerSideDirective],
  template: `
    <tbw-grid
      [columns]="columns"
      [serverSide]="serverSideConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class LiveGridComponent implements OnDestroy {
  grid = injectGrid<Employee>();
  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'status', header: 'Status' },
  ];

  dataSource: ServerSideDataSource<Employee> = {
    async getRows(params: GetRowsParams) {
      const res = await fetch(`/api/employees?start=${params.startNode}&end=${params.endNode}`);
      return res.json();
    },
  };

  serverSideConfig = {
    pageSize: 50,
    dataSource: this.dataSource,
  };

  private ws: WebSocket | null = null;

  constructor() {
    effect(() => {
      const el = this.grid.element();
      if (!el) return;

      this.ws = new WebSocket('wss://api.example.com/employees/live');
      this.ws.onmessage = (event) => {
        const msg = JSON.parse(event.data);
        const tx: RowTransaction<Employee> = {};
        if (msg.type === 'insert') tx.add = [msg.row];
        if (msg.type === 'update') tx.update = [{ id: msg.rowId, changes: msg.changes }];
        if (msg.type === 'delete') tx.remove = [{ id: msg.rowId }];
        el.applyTransaction(tx);
      };
    });
  }

  ngOnDestroy() {
    this.ws?.close();
  }
}
```

### High-Frequency Streams

For data feeds with many updates per second (e.g. financial tickers, IoT sensors), use `applyTransactionAsync()` to automatically batch all updates arriving within a single animation frame:

```ts
// All messages within one frame are merged into a single render
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  grid.applyTransactionAsync({
    update: [{ id: msg.id, changes: msg.changes }],
  });
};
```

### Choosing the Right Method

| Scenario | Method | Animations |
|----------|--------|------------|
| User actions, moderate streams (< 10 msg/s) | `applyTransaction()` | Yes (configurable) |
| High-frequency ticker (100+ msg/s) | `applyTransactionAsync()` | Disabled (batched) |
| Bulk initial load from REST, then switch to streaming | `setDataSource()` + `applyTransaction()` | Mixed |

:::tip
Both methods return a `TransactionResult` with the actual `added`, `updated`, and `removed` row objects — useful for logging, analytics, or triggering side effects.
:::

### Server-Sent Events (SSE)

SSE works the same way — just swap the transport:

```ts
const source = new EventSource('/api/employees/stream');

source.addEventListener('insert', (e) => {
  grid.applyTransaction({ add: [JSON.parse(e.data)] });
});

source.addEventListener('update', (e) => {
  const { id, changes } = JSON.parse(e.data);
  grid.applyTransaction({ update: [{ id, changes }] });
});

source.addEventListener('delete', (e) => {
  const { id } = JSON.parse(e.data);
  grid.applyTransaction({ remove: [{ id }] });
});
```

---

## Composing with Other Plugins

ServerSidePlugin acts as the **data layer** in the grid's unified DataSource architecture. In its simplest form it drives a flat grid with no extra plugins. It also composes with structural plugins (Tree, Row Grouping) and Master-Detail for hierarchical or expandable data.

```mermaid
flowchart TB
    subgraph SSP["ServerSidePlugin (data layer)"]
        direction LR
        GR["getRows()<br/>Block-based fetch"]
        GCR["getChildRows()<br/>On-demand children"]
    end

    GR -- "broadcasts" --> E1["datasource:data"]
    GCR -- "broadcasts" --> E2["datasource:children"]

    E1 --> Flat & Tree & Group
    E2 --> Tree & Group & MD

    Flat["Flat Grid<br/>unclaimed → rendered directly"]
    Tree["TreePlugin<br/>claims root data + children"]
    Group["GroupingRowsPlugin<br/>claims root data + children"]
    MD["MasterDetailPlugin<br/>claims children for detail panels"]
```

**Key concepts:**
- **Flat grid by default**: When no structural plugin (Tree or Row Grouping) claims the data, ServerSidePlugin renders the rows directly. This is the simplest and most common mode — paginated API data driving a virtual-scrolling table.
- **Structural plugins claim data**: When `datasource:data` fires, a structural plugin (Tree or Row Grouping) may *claim* the data by setting `detail.claimed = true`. If none claims it, ServerSidePlugin handles it as flat rows.
- **On-demand children**: When a user expands a tree node, group, or detail row, the display plugin fires a `datasource:fetch-children` query. ServerSidePlugin calls `getChildRows()` and broadcasts the result as `datasource:children` with a `source` discriminator so only the requesting plugin consumes it.
- **Child rows are not paginated**: `getChildRows()` returns all children in a single batch. If the server has a large child set, limit it server-side.

### getChildRows() Interface

When composing with Tree, Row Grouping, or Master-Detail, implement `getChildRows()` on the data source. The `context.source` discriminator tells you which plugin is requesting children:

```typescript
import type { GetChildRowsParams, GetChildRowsResult } from '@toolbox-web/grid/plugins/server-side';

async getChildRows(params: GetChildRowsParams): Promise<GetChildRowsResult> {
  const { source } = params.context;

  if (source === 'tree') {
    const { parentNode } = params.context;
    const res = await fetch(`/api/tree/${parentNode.id}/children`);
    return { rows: await res.json() };
  }

  if (source === 'grouping-rows') {
    const { groupKey } = params.context;
    const res = await fetch(`/api/groups/${groupKey}/rows`);
    return { rows: await res.json() };
  }

  if (source === 'master-detail') {
    const { row } = params.context;
    const res = await fetch(`/api/orders/${row.id}/items`);
    return { rows: await res.json() };
  }

  return { rows: [] };
}
```

### ServerSide + Tree

ServerSidePlugin fetches top-level tree nodes in blocks. TreePlugin claims the data and flattens the hierarchy. For lazy children, TreePlugin fires `datasource:fetch-children` with `source: 'tree'`.

See the [Tree plugin docs](/grid/plugins/tree.md#server-side-data) for full details and examples.

### ServerSide + Row Grouping

ServerSidePlugin fetches group definitions as root data. When a group is expanded, GroupingRowsPlugin fires `datasource:fetch-children` to load the group's rows.

See the [Row Grouping plugin docs](/grid/plugins/grouping-rows.md#server-side-data) for full details and examples.

### ServerSide + Master-Detail

ServerSidePlugin manages the master rows with full virtual scrolling or pagination — loading more master rows on scroll (infinite scroll) or on page navigation, just like it does for flat data, Tree, or Row Grouping. MasterDetail does not claim root data, so master rows flow through ServerSide's block cache and pagination unchanged.

When a detail panel is expanded, MasterDetailPlugin fires `datasource:fetch-children` to load the detail data on demand. Detail data can also be embedded in the master row object, in which case `getChildRows()` is not needed.

See the [Master-Detail plugin docs](/grid/plugins/master-detail.md#server-side-data) for full details and examples.

:::caution[Incompatible Plugins]
The Server-Side plugin **cannot** be used with:

- **[Pivot](/grid/plugins/pivot.md)** — Pivot requires the full dataset to compute aggregations. ServerSide lazy-loads rows in blocks, so pivot aggregation cannot be performed client-side.
:::

## DataSource Event Bus

| Event / Query | Direction | Description |
| --- | --- | --- |
| `datasource:data` | ServerSide → plugins | Root data block loaded. Structural plugins may claim it; unclaimed data is rendered as flat rows |
| `datasource:children` | ServerSide → plugins | Child data loaded. Filtered by `context.source` |
| `datasource:loading` | ServerSide → plugins | Loading state changed (with optional context) |
| `datasource:error` | ServerSide → plugins | Fetch failed (with optional context) |
| `datasource:fetch-children` | Plugins → ServerSide | Query requesting child rows for a context |
| `datasource:is-active` | Plugins → ServerSide | Query checking if a data source is configured |
| `datasource:viewport-mapping` | ServerSide → plugins | Query mapping viewport indices to node-space indices |

## Diagnostic Codes

| Code | Level | Description |
| --- | --- | --- |
| `TBW140` | error | `getRows()` fetch failed |
| `TBW141` | error | `getChildRows()` fetch failed |
| `TBW142` | warn | Plugin requested children but `getChildRows()` is not implemented |
| `TBW143` | info | `datasource:data` was not claimed by any structural plugin (flat grid mode) |

## Limitations

- **Child rows are not paginated.** `getChildRows()` returns all children in a single batch. For tree nodes, group rows, or detail data with many children, limit the response server-side.
- **One structural claim per data event.** Only one of Tree or Row Grouping can claim `datasource:data`. They remain mutually incompatible. When neither is active, data is rendered as flat rows.
- **Master-Detail is not a structural plugin.** It does not claim `datasource:data` — master rows are managed by ServerSide with full virtual scrolling and pagination support. MasterDetail only uses the child data path (`datasource:fetch-children` / `datasource:children`) for on-demand detail loading.

## See Also

- **[Common Patterns — Real-Time Data](/grid/guides/common-patterns.md#real-time--streaming-data)** — Transport-agnostic streaming patterns
- **[Tree Plugin — Server-Side Data](/grid/plugins/tree.md#server-side-data)** — Tree-specific data flow
- **[Row Grouping — Server-Side Data](/grid/plugins/grouping-rows.md#server-side-data)** — Group-specific data flow
- **[Master-Detail — Server-Side Data](/grid/plugins/master-detail.md#server-side-data)** — Detail panel data flow
- **[Filtering](/grid/plugins/filtering.md)** — Column-level filtering with async server-side support
- **[Multi-Sort](/grid/plugins/multi-sort.md)** — Multi-column sorting with async server-side support
- **[Export](/grid/plugins/export.md)** — Export grid data
- **[Common Patterns](/grid/guides/common-patterns.md)** — Full application recipes
- **[Plugins Overview](/grid/plugins.md)** — Plugin compatibility and combinations

---

# Shell Plugin

> Wrap the grid with a header bar (title + toolbar) and a collapsible tool-panel sidebar.

The Shell plugin wraps the grid with an optional **header bar** (title + toolbar) and a
collapsible **tool panel** sidebar. Features like `visibility`, `filtering`, and `pivot`
register their tool panels into this shell.

:::note[On by default in v2.x — opt-in at v3]
In **v2.x** the shell still ships **on by default**, so existing code keeps working without
a code change. It is **deprecated** in that form: from **v3.0.0** the shell becomes opt-in and
you must enable the feature explicitly (see [Migrating to the feature API](#migrating-to-the-feature-api)).
New code should enable it now via `import '@toolbox-web/grid/features/shell'` + `features: { shell: true }`.
:::

## Installation

```ts
import '@toolbox-web/grid/features/shell';
```

The feature import registers the `ShellPlugin` and augments `features` with a typed `shell`
option. Shell configuration types (`ShellConfig`, `ToolPanelDefinition`, …) are exported from
`@toolbox-web/grid/plugins/shell`.

## Basic Usage

Enable the shell by setting `features: { shell }` with a `header.title`. Features like
`visibility` automatically register a tool panel when the shell is active.

#### Angular

```typescript
// Enables the [visibility] input; the shell auto-registers in v2.x.
// For v3, opt in explicitly: import '@toolbox-web/grid-angular/features/shell';
import { GridVisibilityDirective } from '@toolbox-web/grid-angular/features/visibility';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { GridConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-shell-grid',
  imports: [Grid, GridVisibilityDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [gridConfig]="config"
      [visibility]="true"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class ShellGridComponent {
  rows = [];
  config: GridConfig = { shell: { header: { title: 'Employee Data' } } };
}
```

```ts
// ShellBasicDemo.astro
  import '@toolbox-web/grid';
import type { ColumnConfig } from '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/shell';
import '@toolbox-web/grid/features/visibility';
import type { ShellConfig } from '@toolbox-web/grid/plugins/shell';

  const container = document.getElementById('shell-basic-demo-container');
  const grid = queryGrid('#demo-shell-basic');

  if (container && grid) {
    const departments = ['Engineering', 'Sales', 'Marketing', 'Support'];
    const names = ['Alice', 'Bob', 'Carol', 'Dan', 'Eve', 'Frank', 'Grace', 'Henry'];
    function generateRows(count: number) {
      return Array.from({ length: count }, (_, i) => ({
        id: i + 1,
        name: names[i % names.length] + ' ' + (Math.floor(i / names.length) + 1),
        department: departments[i % departments.length],
        salary: 50000 + Math.floor(Math.random() * 50000),
        active: i % 3 !== 0,
      }));
    }

    const shellColumns: ColumnConfig[] = [
      { field: 'id', header: 'ID', type: 'number', width: 80 },
      { field: 'name', header: 'Name', minWidth: 150 },
      { field: 'department', header: 'Department', width: 150 },
      { field: 'salary', header: 'Salary', type: 'number', width: 120 },
      { field: 'active', header: 'Active', type: 'boolean', width: 80 },
    ];
    const sampleData = generateRows(20);

    interface ShellValues {
      showTitle: boolean;
      showHeaderContent: boolean;
      showToolbarButton: boolean;
      showVisibilityPlugin: boolean;
      showCustomPanel: boolean;
      panelPosition: string;
      panelMode: string;
    }

    function rebuild(v: ShellValues) {
      const shellConfig: ShellConfig = {
        header: v.showTitle ? { title: 'Employee Data' } : {},
        toolPanel: {
          position: v.panelPosition as 'left' | 'right',
          mode: v.panelMode as 'overlay' | 'push' | 'dropdown',
        },
      };
      grid.gridConfig = {
        columns: shellColumns,
        features: {
          shell: shellConfig,
          ...(v.showVisibilityPlugin ? { visibility: true } : {}),
        },
      };
      grid.rows = sampleData;

      const shell = grid.getPluginByName('shell');
      if (v.showHeaderContent) {
        shell?.registerHeaderContent({
          id: 'row-count',
          order: 10,
          render: (el) => {
            const span = document.createElement('span');
            span.style.cssText = 'font-size:13px;color:var(--sl-color-gray-3);padding:4px 8px;background:var(--sl-color-gray-6);border-radius:4px;';
            const update = () => { span.textContent = `${grid.rows.length} rows`; };
            const unsub = grid.on('data-change', update);
            el.appendChild(span);
            return () => {
              unsub();
              span.remove();
            };
          },
        });
      } else {
        shell?.unregisterHeaderContent('row-count');
      }

      if (v.showCustomPanel) {
        shell?.registerToolPanel({
          id: 'custom-info',
          title: 'Info Panel',
          icon: 'ℹ',
          tooltip: 'Info Panel',
          render: (el) => {
            el.innerHTML = '<div style="padding:16px;"><h4 style="margin:0 0 8px;">Custom Panel</h4><p style="margin:0;font-size:13px;">This panel was added via registerToolPanel().</p></div>';
            return () => { el.innerHTML = ''; };
          },
        });
      } else {
        shell?.unregisterToolPanel('custom-info');
      }

      if (v.showToolbarButton) {
        shell?.registerToolbarContent({
          id: 'refresh-btn',
          render: (el) => {
            const btn = document.createElement('button');
            btn.className = 'tbw-toolbar-btn';
            btn.title = 'Refresh Data';
            btn.setAttribute('aria-label', 'Refresh Data');
            btn.textContent = '↻';
            btn.addEventListener('click', () => { grid.rows = generateRows(20); });
            el.appendChild(btn);
            return () => btn.remove();
          },
        });
      } else {
        shell?.unregisterToolbarContent('refresh-btn');
      }
    }

    rebuild({
      showTitle: true,
      showHeaderContent: true,
      showToolbarButton: true,
      showVisibilityPlugin: true,
      showCustomPanel: false,
      panelPosition: 'right',
      panelMode: 'overlay',
    });

    container.addEventListener('control-change', ((e: CustomEvent) => {
      rebuild(e.detail.allValues as ShellValues);
    }) as EventListener);
  }
```

## Light DOM Configuration

Configure the shell declaratively using `<tbw-grid-header>` and `<tbw-grid-header-content>`
elements. Still `import '@toolbox-web/grid/features/shell'` so the plugin is present:

```html
<tbw-grid>
  <tbw-grid-header title="Employee Directory">
    <tbw-grid-header-content>
      <span id="row-count">0 employees</span>
    </tbw-grid-header-content>
  </tbw-grid-header>
</tbw-grid>
```

```ts
// ShellLightDomDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/shell';

  const container = document.getElementById('shell-lightdom-wrap');
  if (container) {
    const grid = queryGrid('tbw-grid', container)!;
    const departments = ['Engineering', 'Sales', 'Marketing', 'Support'];
    const names = ['Alice', 'Bob', 'Carol', 'Dan', 'Eve', 'Frank', 'Grace', 'Henry'];

    grid.columns = [
      { field: 'id', header: 'ID', type: 'number', width: 80 },
      { field: 'name', header: 'Name', minWidth: 150 },
      { field: 'department', header: 'Department', width: 150 },
      { field: 'salary', header: 'Salary', type: 'number', width: 120 },
      { field: 'active', header: 'Active', type: 'boolean', width: 80 },
    ];

    grid.rows = Array.from({ length: 20 }, (_, i) => ({
      id: i + 1,
      name: names[i % names.length] + ' ' + (Math.floor(i / names.length) + 1),
      department: departments[i % departments.length],
      salary: 50000 + Math.floor(Math.random() * 50000),
      active: i % 3 !== 0,
    }));
  }
```

## Multiple Tool Panels

Register multiple tool panels — each gets a tab in the sidebar. Panels can be registered via
configuration, the framework wrapper components, or the plugin's runtime `registerToolPanel()`
API. Each panel **requires** a `title`.

#### Angular

```html
<tbw-grid [rows]="rows" [gridConfig]="config">
  <tbw-grid-tool-panel id="filter-panel" title="Filters" icon="🔍">
    <ng-template>
      <p>Filter controls here</p>
    </ng-template>
  </tbw-grid-tool-panel>
</tbw-grid>
```

:::tip[Adapters auto-register the shell (v2.x)]
While **v2.x** is current, the React, Vue, and Angular wrappers register the `ShellPlugin`
automatically when you use a shell wrapper component (`GridToolPanel`, `GridToolButtons`, …) or
pass `features.shell`, so adapter users do not need an explicit shell import. This
auto-registration is a v2.x convenience and is removed at **v3.0.0**, where the shell becomes
opt-in. Each adapter ships a side-effect feature import for the explicit opt-in:
`import '@toolbox-web/grid-react/features/shell'` (and the matching
`grid-vue` / `grid-angular` subpaths). Adding it now is forward-compatible and tree-shakeable.
:::

```ts
// ShellMultiPanelsDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/shell';
import '@toolbox-web/grid/features/visibility';

  const grid = queryGrid('#demo-shell-multi-panels');

  if (grid) {
    const departments = ['Engineering', 'Sales', 'Marketing', 'Support'];
    const names = ['Alice', 'Bob', 'Carol', 'Dan', 'Eve', 'Frank', 'Grace', 'Henry'];

    grid.gridConfig = {
      columns: [
        { field: 'id', header: 'ID', type: 'number', width: 80 },
        { field: 'name', header: 'Name', minWidth: 150 },
        { field: 'department', header: 'Department', width: 150 },
        { field: 'salary', header: 'Salary', type: 'number', width: 120 },
        { field: 'active', header: 'Active', type: 'boolean', width: 80 },
      ],
      features: {
        shell: { header: { title: 'Multi-Panel Demo' } },
        visibility: true,
      },
    };

    grid.rows = Array.from({ length: 20 }, (_, i) => ({
      id: i + 1,
      name: names[i % names.length] + ' ' + (Math.floor(i / names.length) + 1),
      department: departments[i % departments.length],
      salary: 50000 + Math.floor(Math.random() * 50000),
      active: i % 3 !== 0,
    }));

    const shell = grid.getPluginByName('shell');

    // Custom filter panel
    shell?.registerToolPanel({
      id: 'filter',
      title: 'Filter',
      icon: '🔍',
      tooltip: 'Filter data',
      order: 20,
      render: (el) => {
        el.innerHTML = `
          <div style="padding:0.75rem;">
            <div style="margin-bottom:16px;">
              <label style="display:block;margin-bottom:4px;font-size:12px;color:var(--sl-color-gray-3);">Name contains</label>
              <input type="text" placeholder="Search..." style="width:100%;padding:6px 8px;border:1px solid var(--sl-color-gray-5);border-radius:4px;box-sizing:border-box;background:var(--sl-color-gray-6);color:var(--sl-color-text);" />
            </div>
            <div style="margin-bottom:16px;">
              <label style="display:block;margin-bottom:4px;font-size:12px;color:var(--sl-color-gray-3);">Department</label>
              <select style="width:100%;padding:6px 8px;border:1px solid var(--sl-color-gray-5);border-radius:4px;box-sizing:border-box;background:var(--sl-color-gray-6);color:var(--sl-color-text);">
                <option value="">All</option>
                <option value="Engineering">Engineering</option>
                <option value="Sales">Sales</option>
                <option value="Marketing">Marketing</option>
                <option value="Support">Support</option>
              </select>
            </div>
          </div>
        `;
        return () => { el.innerHTML = ''; };
      },
    });

    // Custom settings panel
    shell?.registerToolPanel({
      id: 'settings',
      title: 'Settings',
      icon: '⚙',
      tooltip: 'Grid settings',
      order: 50,
      render: (el) => {
        el.innerHTML = `
          <div style="padding:0.75rem;">
            <label style="display:flex;align-items:center;gap:8px;margin-bottom:12px;"><input type="checkbox" checked /><span>Row hover effect</span></label>
            <label style="display:flex;align-items:center;gap:8px;margin-bottom:12px;"><input type="checkbox" checked /><span>Alternating row colors</span></label>
            <label style="display:flex;align-items:center;gap:8px;"><input type="checkbox" /><span>Compact mode</span></label>
          </div>
        `;
        return () => { el.innerHTML = ''; };
      },
    });
  }
```

## Toolbar Buttons

Add custom buttons to the shell toolbar using framework wrapper components or light-DOM
`<tbw-grid-tool-buttons>`:

#### Angular

```html
<tbw-grid [rows]="rows" [gridConfig]="config">
  <tbw-grid-tool-buttons>
    <button (click)="exportData()">📥 Export</button>
    <button (click)="printGrid()">🖨️ Print</button>
  </tbw-grid-tool-buttons>
</tbw-grid>
```

```ts
// ShellToolbarButtonsDemo.astro
  import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/shell';

  const wrap = document.getElementById('shell-toolbar-wrap');
  const grid = queryGrid('tbw-grid', wrap!);

  if (grid && wrap) {
    const names = ['Alice', 'Bob', 'Carol', 'Dan', 'Eve', 'Frank', 'Grace', 'Henry'];
    const depts = ['Engineering', 'Sales', 'Marketing', 'Support'];

    grid.columns = [
      { field: 'id', header: 'ID', type: 'number', width: 80 },
      { field: 'name', header: 'Name', minWidth: 150 },
      { field: 'department', header: 'Department', width: 150 },
      { field: 'salary', header: 'Salary', type: 'number', width: 120 },
    ];

    grid.rows = Array.from({ length: 15 }, (_, i) => ({
      id: i + 1,
      name: names[i % names.length] + ' ' + (Math.floor(i / names.length) + 1),
      department: depts[i % depts.length],
      salary: 50000 + Math.floor(Math.random() * 50000),
    }));

    const exportBtn = wrap.querySelector('[title="Export"]');
    exportBtn?.addEventListener('click', () => alert('Export clicked!'));

    const printBtn = wrap.querySelector('[title="Print"]');
    printBtn?.addEventListener('click', () => alert('Print clicked!'));
  }
```

## Shell Configuration Reference

All options live under `features.shell` and are typed by `ShellConfig`
(from `@toolbox-web/grid/plugins/shell`):

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `header.title` | `string` | — | Title text in the header bar |
| `header.visible` | `boolean` | `true` | Render the header bar. Set `false` to suppress the entire `.tbw-shell-header` and own all chrome yourself |
| `header.toolPanelToggle` | `boolean` | `true` | Render the built-in panel toggle button + separator |
| `toolPanel.position` | `'left' \| 'right'` | `'right'` | Sidebar position |
| `toolPanel.width` | `number` | `280` | Sidebar width in pixels |
| `toolPanel.defaultOpen` | `string` | — | Accordion section to auto-expand on first open. **Deprecated:** in v2.x this also opens the sidebar; in v3.0.0 it will only pre-select the section (see [#259](https://github.com/OysteinAmundsen/toolbox/issues/259)). Combine with `initialState: 'open'` for forward-compatible behavior. |
| `toolPanel.initialState` | `'open' \| 'closed'` | `'closed'` | Whether the sidebar starts open on grid load. Overrides the legacy `defaultOpen` open-on-load behavior when set. |
| `toolPanel.locked` | `boolean` | `false` | Lock the sidebar open. Implies `initialState: 'open'`, makes `closeToolPanel()` a no-op, and hides the built-in toggle button. |
| `toolPanel.persistState` | `boolean` | `false` | Remember open/closed state |
| `toolPanel.closeOnClickOutside` | `boolean` | `false` | Close on outside click (ignored in `mode: 'push'` or when `locked: true`; `'dropdown'` always light-dismisses) |
| `toolPanel.mode` | `'overlay' \| 'push' \| 'dropdown'` | `'overlay'` | `'overlay'` floats over the grid; `'push'` reflows the grid sideways so all cells stay visible; `'dropdown'` renders the whole sidebar as an anchored popover |

## Tool-Panel Layout Modes

The tool panel supports three layout modes — pick whichever fits the viewport you're targeting.

- **`'overlay'`** (default): the panel is positioned **over** the grid content. Opening it does not change the grid's available width. Best for narrow viewports where shrinking the grid would leave too little room for the data.
- **`'push'`**: the panel is laid out as a **sibling** of the grid content in a flex row. Opening it shrinks the grid's available width; the grid's `ResizeObserver` re-runs column virtualization, so cells that an overlay panel would hide remain reachable. Best for desktop layouts.
- **`'dropdown'`**: the entire sidebar (the full accordion) renders as an **anchored popover** built on the native [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API). It floats above all other content in the top layer, is dismissed on `Escape` or click-outside, and is positioned via [CSS anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning) where supported (with a JS bounding-rect fallback). The anchor is resolved by priority: an explicit `anchor` passed to `openToolPanel()` → the built-in toggle button → the grid corner. Best for compact toolbars and bring-your-own trigger buttons (e.g. a "columns" button in a custom column header).

```ts
import '@toolbox-web/grid/features/shell';

grid.gridConfig = {
  features: {
    shell: {
      toolPanel: {
        position: 'right',
        mode: 'push', // grid reflows when the panel opens/closes
      },
    },
  },
};
```

In `'push'` mode the user-facing resize handle is hidden (the panel's width is part of the layout, so drag-to-resize would fight the flex container) and `closeOnClickOutside` is treated as a no-op (there is no overlap to dismiss against). Drive the width via the `--tbw-tool-panel-width` CSS variable instead.

### Dropdown mode + a custom column-header trigger

`'dropdown'` mode shines when you want the column chooser to hang off your **own** button rather than the built-in toolbar toggle. Pass that button as the `anchor` when you open the panel, and the popover positions itself directly below it:

```ts
const shell = grid.getPluginByName('shell');
// Mark your trigger so the popover can re-find it after a structural re-render.
columnsButton.setAttribute('data-panel-toggle', '');
columnsButton.addEventListener('click', () => {
  shell?.openToolPanel('columns', { anchor: columnsButton });
});
```

:::caution[Mark a custom trigger with `data-panel-toggle`]
A custom trigger button **must** carry the `data-panel-toggle` attribute. Toggling a column's visibility or reordering columns from inside the panel triggers a structural re-render that **rebuilds the trigger node** — so the element reference you passed as `anchor` is detached and can no longer be re-anchored. The shell re-resolves the anchor after every re-render via the `[data-panel-toggle]` selector; without it, an open dropdown falls back to the grid corner instead of staying under your button.
:::

The demo below renders a utility-type column whose **header** hosts a custom `▥` button. Clicking it opens the full tool panel as a dropdown anchored to that button — no toolbar required.

```ts
// ShellDropdownDemo.astro
  import '@toolbox-web/grid';
import type { ColumnConfig } from '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/shell';
import '@toolbox-web/grid/features/visibility';

  const grid = queryGrid('#demo-shell-dropdown');

  if (grid) {
    const departments = ['Engineering', 'Sales', 'Marketing', 'Support'];
    const names = ['Alice', 'Bob', 'Carol', 'Dan', 'Eve', 'Frank', 'Grace', 'Henry'];

    // A utility column: not bound to data — its header hosts the dropdown trigger.
    const columnsTrigger: ColumnConfig = {
      field: '__columns__',
      utility: true,
      header: '',
      width: 48,
      sortable: false,
      resizable: false,
      headerRenderer: (ctx) => {
        const btn = document.createElement('button');
        btn.type = 'button';
        btn.className = 'tbw-columns-trigger';
        btn.textContent = '▥';
        btn.title = 'Choose columns';
        btn.setAttribute('aria-label', 'Choose columns');
        btn.setAttribute('aria-haspopup', 'dialog');
        // INVARIANT: a custom dropdown trigger MUST carry `data-panel-toggle`.
        // Toggling a column from inside the panel rebuilds this header (and so
        // recreates this very button), detaching the element the popover was
        // anchored to. The shell re-resolves the anchor via the
        // `[data-panel-toggle]` selector, so without this attribute the dropdown
        // would re-anchor to the grid corner instead of back to this button.
        btn.setAttribute('data-panel-toggle', '');
        btn.addEventListener('click', (e) => {
          e.stopPropagation();
          const shell = grid.getPluginByName('shell');
          if (shell?.isToolPanelOpen) {
            shell.closeToolPanel();
          } else {
            // Anchor the dropdown popover directly to this header button.
            shell?.openToolPanel('columns', { anchor: btn });
          }
        });
        ctx.cellEl.style.justifyContent = 'center';
        return btn;
      },
    };

    grid.gridConfig = {
      columns: [
        { field: 'id', header: 'ID', type: 'number', width: 70 },
        { field: 'name', header: 'Name', minWidth: 140, lockVisible: true },
        { field: 'department', header: 'Department', width: 150 },
        { field: 'salary', header: 'Salary', type: 'number', width: 110 },
        { field: 'active', header: 'Active', type: 'boolean', width: 80 },
        columnsTrigger,
      ],
      features: {
        // No built-in toolbar toggle — the dropdown is driven entirely by the
        // custom column-header button.
        shell: { header: { title: 'Employees', toolPanelToggle: false }, toolPanel: { mode: 'dropdown' } },
        visibility: true,
      },
    };

    grid.rows = Array.from({ length: 20 }, (_, i) => ({
      id: i + 1,
      name: names[i % names.length] + ' ' + (Math.floor(i / names.length) + 1),
      department: departments[i % departments.length],
      salary: 50000 + Math.floor(Math.random() * 50000),
      active: i % 3 !== 0,
    }));
  }
```

In `'dropdown'` mode the resize handle is hidden, the popover is capped to the viewport (`max-height: min(70vh, 480px)`) with internal scrolling for tall accordions, and dismissal (Escape / click-outside) is always active regardless of `closeOnClickOutside`.

## Styling the Shell

`<tbw-grid>` renders into the **light DOM**, so the shell's internals are reachable from any outer stylesheet — no `::part()` needed. Theme-level overrides applied to a top-level CSS file affect every grid in the application uniformly.

**Stable selectors:**

| Selector | Element |
|----------|---------|
| `tbw-grid .tbw-shell-header` | Header bar (title + content + toolbar) |
| `tbw-grid .tbw-shell-title` | Title element |
| `tbw-grid .tbw-shell-toolbar` | Toolbar (flex container; custom content + toggle) |
| `tbw-grid .tbw-toolbar-btn` | Buttons inside the toolbar (incl. panel toggle) |
| `tbw-grid [data-panel-toggle]` | The single panel toggle button |
| `tbw-grid .tbw-toolbar-separator` | Separator between custom content and the toggle |
| `tbw-grid .tbw-tool-panel` | Tool-panel sidebar |
| `tbw-grid .tbw-accordion-header` | Tool-panel section header (one per registered panel) |

**Recipe — move the panel toggle to the start of the toolbar (left in LTR):**

The toolbar is a flex row, so reordering is purely a CSS concern — use `order` on both the toggle and its separator so they stay grouped together:

```css
/* App-level theme — affects every <tbw-grid> uniformly */
tbw-grid [data-panel-toggle],
tbw-grid .tbw-toolbar-separator {
  order: -1;
}
```

No grid configuration is required; this is the recommended way to standardize toolbar layout across an application's grids.

## Bring Your Own Tool-Panel Toggle

If you need to replace the built-in toggle button entirely — for example, to use a design-system button instead of styling `.tbw-toolbar-btn` — set `header.toolPanelToggle: false`. The grid will not render the built-in button **or** the auto-inserted separator next to it; tool panels themselves remain fully functional and can be toggled from any element via the plugin's `toggleToolPanel()`, opened directly on a specific section via `openToolPanel(panelId)`, or driven section-by-section with `toggleToolPanelSection(id)`.

```ts
import '@toolbox-web/grid/features/shell';

const shell = grid.getPluginByName('shell');

const config = {
  features: {
    shell: {
      header: {
        title: 'Employees',
        toolPanelToggle: false, // suppress built-in <button data-panel-toggle> + separator
        toolbarContents: [
          {
            id: 'my-buttons',
            render: (container) => {
              const filters = document.createElement('my-button');
              filters.textContent = 'Filters';
              filters.addEventListener('click', () => shell?.openToolPanel('filters'));

              const settings = document.createElement('my-button');
              settings.textContent = 'Settings';
              settings.addEventListener('click', () => shell?.openToolPanel('settings'));

              container.append(filters, settings);
            },
          },
        ],
      },
    },
  },
};
```

Passing a `panelId` to `openToolPanel()` jumps straight to that accordion section (one click, no double-tap). It takes precedence over `toolPanel.defaultOpen`; if the ID isn't registered, the call falls back to default behavior and emits a `TBW072` warning.

## Hide the Shell Header Bar Entirely

`toolPanelToggle: false` removes the built-in toggle button but keeps the header bar (with its title and any toolbar contents). To suppress the **entire** `.tbw-shell-header` bar — for example when you want to open tool panels from a custom column header icon and own all chrome yourself — set `header.visible: false`.

```ts
import '@toolbox-web/grid/features/shell';

const shell = grid.getPluginByName('shell');

const config = {
  columns: [
    // …
    {
      field: '__actions',
      width: 56,
      utility: true, // excluded from print, export, reorder, visibility, etc.
      resizable: false,
      sortable: false,
      headerRenderer: () => {
        const btn = document.createElement('button');
        btn.type = 'button';
        btn.textContent = '⚙';
        btn.setAttribute('aria-label', 'Open tool panel');
        btn.addEventListener('click', () => shell?.toggleToolPanel());
        return btn;
      },
    },
  ],
  features: {
    shell: {
      header: { visible: false },
      toolPanel: {
        closeOnClickOutside: true, // optional — see below
      },
    },
  },
};
```

When `header.visible: false`, tool panels remain fully functional and are opened with the plugin's `toggleToolPanel()` / `openToolPanel(panelId)` from any element you like. Because there is no header toggle to close the panel, the grid provides three additional dismissal affordances:

- **Close button** — a small `✕` button (exposed as the `tool-panel-close` CSS part) is rendered to dismiss the panel. With a single panel it sits inline on the first accordion header row; with multiple panels it gets its own row at the top of the panel (exposed as the `tool-panel-header` CSS part). It is omitted when `toolPanel.locked` is `true` (a locked panel cannot be closed) and in `dropdown` mode, where the popover already light-dismisses on <kbd>Esc</kbd> / click-outside.
- **Escape key** — pressing <kbd>Esc</kbd> closes an open **overlay** panel. It yields to more specific handlers (e.g. an active cell editor that has already handled the key), and is a no-op for `push`-mode panels, which are persistent sidebars.
- **Click-outside** — set `toolPanel.closeOnClickOutside: true` to dismiss an open overlay panel when clicking anywhere in the window outside the panel. This is opt-in and, like Esc, is a no-op in `push` mode.

`header.visible: false` keeps the shell active (the panel overlay still mounts); it only suppresses the header bar element. This is the supported alternative to hiding `.tbw-shell-header` with CSS.

## Migrating to the Feature API

The shell used to be part of grid **core**: auto-registered with no import, driven by
`grid.register*` / `openToolPanel` element delegates, with its config types exported from the
package root. Those surfaces are **deprecated** and will be **removed in v3.0.0**. The `shell`
configuration object itself is augmented onto `gridConfig` by the plugin and is **not** deprecated.
Migrate as follows:

| Deprecated (v2.x, removed at v3) | Use instead |
|----------------------------------|-------------|
| _Implicit_ shell (no import) | `import '@toolbox-web/grid/features/shell'` |
| `grid.registerToolPanel(panel)` | `grid.getPluginByName('shell')?.registerToolPanel(panel)` |
| `grid.unregisterToolPanel(id)` | `grid.getPluginByName('shell')?.unregisterToolPanel(id)` |
| `grid.registerHeaderContent(c)` | `grid.getPluginByName('shell')?.registerHeaderContent(c)` |
| `grid.registerToolbarContent(c)` | `grid.getPluginByName('shell')?.registerToolbarContent(c)` |
| `grid.openToolPanel(id)` / `closeToolPanel()` / `toggleToolPanel()` | `grid.getPluginByName('shell')?.openToolPanel(id)` (same method names) |
| Shell types from `@toolbox-web/grid` | Shell types from `@toolbox-web/grid/plugins/shell` |

Notes:

- In **v2.x** the shell is still auto-registered, so unmigrated code keeps working — the
  imperative `grid.*` shell delegates emit a one-time **TBW076** deprecation warning. The
  top-level `config.shell` field is a plugin augmentation (**not** deprecated) and
  `refreshShellHeader()` is merged/handled silently.
- For advanced/explicit control you can register the plugin directly:
  `plugins: [new ShellPlugin(shellConfig)]` (from `@toolbox-web/grid/plugins/shell`).
- **Adapters auto-register** the `ShellPlugin` in **v2.x**, so React/Vue/Angular users need no
  change; this auto-registration is removed at **v3.0.0** (opt-in). The forward-compatible opt-in
  is the adapter-specific side-effect import
  `import '@toolbox-web/grid-{react,vue,angular}/features/shell'`.
- From **v3.0.0** the shell is opt-in: shell usage without the feature/plugin throws a clear
  error with a migration link.

## How the Shell Wraps the Grid

The shell is unusual among plugins: most plugins **enrich** the grid (tagging rows, decorating
cells), but the shell **wraps** it — it consumes the freshly built grid DOM and renders its own
chrome (header bar + tool-panel sidebar) _around_ it. It does this from the
`afterStructuralRender()` lifecycle hook, relocating the existing `.tbw-grid-content` node into
the shell wrapper (preserving the subtree, its listeners, and the grid's cached refs) rather than
re-creating it.

If you want to build **another** grid-wrapping plugin, this pattern is documented as a reusable
recipe in [Plugin Architecture → Wrapping plugins](/grid/plugin-development/architecture.md#wrapping-plugins-host-dom-chrome).

## See Also
- **[Filtering](/grid/plugins/filtering.md)** — Registers a filter tool panel into the shell
- **[Pivot](/grid/plugins/pivot.md)** — Registers a pivot configuration tool panel
- **[Core Features](/grid/core.md)** — Columns, renderers, formatters, events, and methods
- **[Plugins Overview](/grid/plugins.md)** — Plugin compatibility and combinations

---

# Sticky Rows Plugin

> Pin selected data rows below the header as the user scrolls past them.

The **Sticky Rows** plugin keeps selected data rows pinned just under the
header while the user scrolls past them. Useful for section markers, group
headers in flat lists, "you are here" anchors, and any scenario where you
want a row to remain visible after it would naturally scroll out of view.

Stuck rows are **clones** of the real rows — the originals stay in the data
flow, remain interactive, and continue to participate in keyboard navigation.
Clones are decorative, marked `aria-hidden="true"`, and inherit the row's
column-template alignment so they line up perfectly with the data below.

## Demo

Scroll the grid below. Section-marker rows (`— A —`, `— B —`, …) pin under
the header as they scroll past. Switch between **push** and **stack** mode
in the controls to compare behaviors, and increase _Rows per section_ to
see longer scroll runs between markers.

## Installation

```ts
import '@toolbox-web/grid/features/sticky-rows';
```

Or use the plugin directly:

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

## Basic Usage

Provide an `isSticky` predicate — either the **name of a boolean field** on
your row data, or a **function** receiving `(row, index)` and returning a
truthy value when the row should be sticky.

#### Angular

```typescript
// Feature import - enables the [stickyRows] input
import { GridStickyRowsDirective } from '@toolbox-web/grid-angular/features/sticky-rows';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridStickyRowsDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [stickyRows]="stickyConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [/* ... */];

  columns: ColumnConfig[] = [
    { field: 'label', header: 'Label' },
    { field: 'value', header: 'Value' },
  ];

  // Field-name shorthand: any row whose `isSection` is truthy is sticky.
  stickyConfig = { isSticky: 'isSection' };
}
```

## Modes

### `'push'` (default)

Only one sticky row is shown at a time. As the next sticky row approaches
from below, it slides the previous one upward and out of view (iOS
section-header behavior).

```ts
features: { stickyRows: { isSticky: 'isSection', mode: 'push' } }
```

Best for: long flat lists where each section anchor should be transient.

### `'stack'`

Sticky rows accumulate below the header up to `maxStacked`. When the cap is
reached, the oldest (lowest-index) entry is evicted from the top so the
most recently passed marker is always visible.

```ts
features: {
  stickyRows: {
    isSticky: 'isSection',
    mode: 'stack',
    maxStacked: 3,
  },
}
```

Best for: hierarchical breadcrumbs where multiple levels of context should
remain visible.

## Predicate Function

For more nuanced selection (computed flags, derived fields, every Nth row,
etc.), pass a function:

```ts
features: {
  stickyRows: {
    isSticky: (row, index) => row.priority === 'critical' || index % 50 === 0,
  },
}
```

The predicate runs once per row whenever the row set changes (via
`afterRender`), so keep it cheap.

## Configuration Reference

| Option       | Type                                              | Default      | Description                                                  |
| ------------ | ------------------------------------------------- | ------------ | ------------------------------------------------------------ |
| `isSticky`   | `string \| (row, index) => unknown`               | _required_   | Field name shorthand or predicate function.                  |
| `mode`       | `'push' \| 'stack'`                               | `'push'`     | How concurrent sticky rows are presented.                    |
| `maxStacked` | `number`                                          | `Infinity`   | Cap on stacked clones (only applies when `mode: 'stack'`).   |
| `className`  | `string`                                          | _(none)_     | Optional class applied to the container and every clone.     |

## Styling

The plugin renders a single `<div class="tbw-sticky-rows">` between the
header and the rows region. Each clone carries `class="tbw-sticky-row"` and
the data attribute `data-sticky-row="<rowIndex>"`.

The container reads three CSS custom properties from the active theme:

- `--tbw-z-layer-sticky-rows` — z-index (defaults to `22`)
- `--tbw-color-bg` / `--tbw-color-panel-bg` — background fill
- `--tbw-color-border` — bottom-shadow color separating clones from data

Override with your own scoped rules:

```css
tbw-grid .tbw-sticky-row {
  background: var(--my-section-bg);
  font-weight: 600;
}
```

## Accessibility

- Clones are marked `aria-hidden="true"` so screen readers don't double-read.
- Focus styles and `tabindex` are stripped from clones — keyboard navigation
  goes through the underlying rows only.
- The originals retain their `aria-rowindex`, `role="row"`, and full cell
  semantics, so screen readers describe row position relative to the dataset.

## Bundle Size

The plugin is **≈4 kB gzipped** (ESM) / **≈2 kB gzipped** (UMD). It does
not pull in any other plugins or core internals.

## See Also

- [Pinned Rows](/grid/plugins/pinned-rows.md) — for non-data totals/aggregation rows
- [Master / Detail](/grid/plugins/master-detail.md) — for expanded child rows
- [Tree](/grid/plugins/tree.md) — for hierarchical data

---

# Tooltip Plugin

> Display popover tooltips for truncated header and cell text, with per-column overrides.

The Tooltip plugin shows popover tooltips when header or cell text overflows its container. It uses the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) with CSS anchor positioning for a native, consistent experience across browsers — with a JavaScript fallback for older browsers.

Tooltips appear automatically on hover. Per-column overrides let you provide custom static text or dynamic content derived from row data.

## Installation

```ts
import '@toolbox-web/grid/features/tooltip';
```

## Basic Usage

#### Angular

```typescript
import { GridTooltipDirective } from '@toolbox-web/grid-angular/features/tooltip';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  selector: 'app-grid',
  imports: [Grid, GridTooltipDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [tooltip]="true"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class GridComponent {
  rows = [];
  columns = [
    { field: 'id', header: 'ID', width: 60 },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email Address' },
  ];
}
```

## Demo

Hover over truncated column headers or cell values to see tooltips. Toggle header/cell tooltips with the controls. The **Job Title** column demonstrates a custom `headerTooltip` string and a dynamic `cellTooltip` function.

```ts
// TooltipDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/tooltip';

const container = document.getElementById('tooltip-default-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container)!;

  const sampleData = [
    { id: 1, name: 'Alice Johnson', email: 'alice.johnson@acmecorporation.com', department: 'Engineering & Development', role: 'Senior Software Engineer' },
    { id: 2, name: 'Bob Smith', email: 'bob.smith@acmecorporation.com', department: 'Marketing & Communications', role: 'Brand Strategy Director' },
    { id: 3, name: 'Carol Williams', email: 'carol.williams@acmecorporation.com', department: 'Human Resources', role: 'Recruitment Specialist' },
    { id: 4, name: 'David Brown', email: 'david.brown@acmecorporation.com', department: 'Sales & Business Development', role: 'Regional Account Manager' },
    { id: 5, name: 'Eve Davis', email: 'eve.davis@acmecorporation.com', department: 'Finance & Accounting', role: 'Senior Financial Analyst' },
  ];

  function rebuild(opts: Record<string, unknown>) {
    grid.gridConfig = {
      columns: [
        { field: 'id', header: 'ID', width: 50 },
        { field: 'name', header: 'Full Name', width: 100 },
        { field: 'email', header: 'Email Address', width: 120 },
        { field: 'department', header: 'Department / Division', width: 110 },
        { field: 'role', header: 'Job Title & Responsibilities', width: 120,
          headerTooltip: 'The official job title and primary area of responsibility',
          cellTooltip: (ctx) => `${ctx.row.name} — ${ctx.value}` },
      ],
      features: {
        tooltip: {
          header: (opts.header as boolean) ?? true,
          cell: (opts.cell as boolean) ?? true,
        },
      },
    };
    grid.rows = sampleData;
  }

  rebuild({ header: true, cell: true });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues);
  }) as EventListener);
}
```

## Configuration

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `header` | `boolean` | `true` | Enable automatic tooltips on overflowing header text |
| `cell` | `boolean` | `true` | Enable automatic tooltips on overflowing cell text |

## Per-Column Overrides

Override tooltip behavior on individual columns with `headerTooltip` and `cellTooltip`:

```ts
const columns = [
  // Static header tooltip
  { field: 'revenue', header: 'Rev.', headerTooltip: 'Total revenue in USD (before tax)' },

  // Dynamic cell tooltip that adds context beyond the cell value
  { field: 'name', cellTooltip: (ctx) => `Hired ${new Date(ctx.row.hireDate).toLocaleDateString()}` },

  // Disable tooltip for a specific column
  { field: 'actions', cellTooltip: false, headerTooltip: false },
];
```

:::tip
If the cell value itself isn't a plain `row[field]` read (for example, a "Full Name" computed from `firstName + lastName`), use [`valueAccessor`](/grid/core.md#value-accessors) on the column rather than computing it inside `cellTooltip`. The accessor runs once per row and is reused by sorting, filtering, exports, and the default tooltip — `cellTooltip` only adds extra information beyond the cell's value.
:::

| Property | Type | Description |
| -------- | ---- | ----------- |
| `headerTooltip` | `false \| string \| (ctx) => string \| null` | Override header tooltip. `false` disables it, a string sets static text, a function returns dynamic text (return `null` to suppress). |
| `cellTooltip` | `false \| string \| (ctx) => string \| null` | Override cell tooltip. Same signature as `headerTooltip`. The callback receives `{ value, row, field, column }`. |

## Styling

The tooltip popover includes a directional arrow that automatically flips when the tooltip appears above the cell. It supports CSS custom properties:

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-tooltip-bg` | `var(--tbw-color-panel-bg)` | Tooltip background color |
| `--tbw-tooltip-fg` | `var(--tbw-color-panel-fg)` | Tooltip text color |
| `--tbw-tooltip-border` | `var(--tbw-color-border)` | Tooltip border and arrow color |
| `--tbw-tooltip-shadow` | `0 2px 8px rgba(0,0,0,.15)` | Tooltip box shadow |
| `--tbw-tooltip-radius` | `var(--tbw-border-radius)` | Border radius |
| `--tbw-tooltip-arrow-offset` | `12px` | Horizontal offset of the arrow from the left edge |

```css
tbw-grid {
  --tbw-tooltip-bg: #1e1e2e;
  --tbw-tooltip-fg: #cdd6f4;
  --tbw-tooltip-border: #45475a;
}
```

---

# Tree Plugin

> Display hierarchical data as an expandable tree.

The Tree plugin transforms your flat grid into a hierarchical tree view with expandable parent-child relationships. Great for file explorers, organizational charts, nested categories, or any data with a natural hierarchy.

## Installation

```ts
import '@toolbox-web/grid/features/tree';
```

## Basic Usage

Just point the feature at the field containing child items (defaults to `children`) and the grid handles all the expand/collapse behavior, indentation, and icons automatically.

#### Angular

```typescript
// Feature import - enables the [tree] input
import { GridTreeDirective } from '@toolbox-web/grid-angular/features/tree';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-file-explorer',
  imports: [Grid, GridTreeDirective],
  template: `
    <tbw-grid
      [rows]="files"
      [columns]="columns"
      [tree]="{ childrenField: 'children', indentWidth: 24 }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class FileExplorerComponent {
  files = [/* hierarchical data */];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'type', header: 'Type' },
    { field: 'size', header: 'Size' }
  ];
}
```

## Demo

Toggle the controls to explore animation, indentation, and expand behavior.

```ts
// TreeDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/tree';

const container = document.getElementById('tree-default-demo');
if (container) {
  const fileSystemData = [
    {
      name: 'Documents', type: 'folder', size: '-',
      children: [
        { name: 'Resume.pdf', type: 'file', size: '2.4 MB' },
        { name: 'Cover Letter.docx', type: 'file', size: '156 KB' },
        {
          name: 'Projects', type: 'folder', size: '-',
          children: [
            { name: 'Project A', type: 'folder', size: '-', children: [{ name: 'notes.txt', type: 'file', size: '12 KB' }] },
            { name: 'Project B', type: 'folder', size: '-' },
          ],
        },
      ],
    },
    {
      name: 'Pictures', type: 'folder', size: '-',
      children: [
        { name: 'vacation.jpg', type: 'file', size: '4.2 MB' },
        { name: 'family.png', type: 'file', size: '3.1 MB' },
      ],
    },
    { name: 'readme.md', type: 'file', size: '1 KB' },
  ];
  const columns = [
    { field: 'name', header: 'Name' },
    { field: 'type', header: 'Type' },
    { field: 'size', header: 'Size' },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(opts: Record<string, unknown>) {
    grid.gridConfig = {
      columns,
      features: {
        tree: {
          animation: opts.animation === 'false' ? false : (opts.animation as string) ?? 'slide',
          childrenField: 'children',
          defaultExpanded: opts.defaultExpanded as boolean ?? false,
          indentWidth: (opts.indentWidth as number) ?? 20,
          showExpandIcons: opts.showExpandIcons as boolean ?? true,
        } as any,
      },
    };
    grid.rows = fileSystemData;
  }

  rebuild({ animation: 'slide', defaultExpanded: false, indentWidth: 20, showExpandIcons: true });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues);
  }) as EventListener);
}
```

### With Pinned Columns

Use `treeColumn` to control which column displays the tree toggle when combining tree with pinned (sticky) columns. By default the toggle appears on the first visible column — set `treeColumn` to explicitly target a wider column like `'name'`.

```ts
// TreePinnedColumnsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/pinned-columns';
import '@toolbox-web/grid/features/tree';

const container = document.getElementById('tree-pinned-columns-demo');
if (container) {
  const orgData = [
    {
      id: 1, name: 'Engineering', department: 'Tech', headcount: 42, budget: '$2.1M',
      children: [
        {
          id: 2, name: 'Frontend', department: 'Tech', headcount: 18, budget: '$900K',
          children: [
            { id: 3, name: 'Alice Chen', department: 'Tech', headcount: 1, budget: '$120K' },
            { id: 4, name: 'Bob Lee', department: 'Tech', headcount: 1, budget: '$115K' },
            { id: 5, name: 'Carol Wu', department: 'Tech', headcount: 1, budget: '$110K' },
          ],
        },
        {
          id: 6, name: 'Backend', department: 'Tech', headcount: 24, budget: '$1.2M',
          children: [
            { id: 7, name: 'Dan Kim', department: 'Tech', headcount: 1, budget: '$130K' },
            { id: 8, name: 'Eve Park', department: 'Tech', headcount: 1, budget: '$125K' },
          ],
        },
      ],
    },
    {
      id: 10, name: 'Marketing', department: 'Business', headcount: 15, budget: '$800K',
      children: [
        { id: 11, name: 'Frank Diaz', department: 'Business', headcount: 1, budget: '$95K' },
        { id: 12, name: 'Grace Ito', department: 'Business', headcount: 1, budget: '$90K' },
      ],
    },
    {
      id: 20, name: 'Sales', department: 'Business', headcount: 20, budget: '$1.5M',
      children: [
        { id: 21, name: 'Hank Novak', department: 'Business', headcount: 1, budget: '$100K' },
        { id: 22, name: 'Ivy Shah', department: 'Business', headcount: 1, budget: '$105K' },
      ],
    },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(opts: Record<string, unknown>) {
    const treeColumn = opts.treeColumn === '(first)' ? undefined : (opts.treeColumn as string);
    grid.gridConfig = {
      columns: [
        { field: 'id', header: 'ID', width: 60, pinned: opts.pinId ? 'left' : undefined },
        { field: 'name', header: 'Name', width: 180, pinned: opts.pinName ? 'left' : undefined },
        { field: 'department', header: 'Department', width: 120 },
        { field: 'headcount', header: 'Headcount', width: 100, type: 'number' },
        { field: 'budget', header: 'Budget', width: 100 },
      ],
      features: {
        tree: {
          childrenField: 'children',
          defaultExpanded: true,
          indentWidth: (opts.indentWidth as number) ?? 20,
          treeColumn,
        } as any,
        pinnedColumns: true,
      },
    };
    grid.rows = orgData;
  }

  rebuild({ treeColumn: 'name', indentWidth: 20, pinId: true, pinName: true });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues);
  }) as EventListener);
}
```

### Server-Side Data

> **Requires:** `ServerSidePlugin` — [see Server-Side Plugin](/grid/plugins/server-side.md)

For large hierarchical datasets, use `ServerSidePlugin` to fetch top-level tree nodes in blocks as the user scrolls. TreePlugin claims the incoming data and renders the hierarchy. Children can be embedded in the response or fetched lazily via `getChildRows()`.

#### Angular

```typescript
import { GridTreeDirective } from '@toolbox-web/grid-angular/features/tree';
import { GridServerSideDirective } from '@toolbox-web/grid-angular/features/server-side';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-server-tree',
  imports: [Grid, GridTreeDirective, GridServerSideDirective],
  template: `
    <tbw-grid
      [columns]="columns"
      [serverSide]="serverSideConfig"
      [tree]="{ childrenField: 'children' }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class ServerTreeComponent {
  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'role', header: 'Role' },
  ];

  serverSideConfig = {
    pageSize: 50,
    dataSource: {
      async getRows(params: any) {
        const res = await fetch(`/api/tree?start=${params.startNode}&end=${params.endNode}`);
        return res.json();
      },
    },
  };
}
```

```ts
// TreeLazyLoadingDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/server-side';
import '@toolbox-web/grid/features/tree';

const container = document.getElementById('tree-lazy-loading-demo');
if (container) {
  const statusEl = container.querySelector('.load-status')!;

  // Generate a large hierarchical dataset on the client to simulate a server
  function generateTreeData(count: number) {
    const departments = ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'];
    const data = [];
    for (let i = 0; i < count; i++) {
      const dept = departments[i % departments.length];
      const teamSize = 2 + (i % 4);
      const children = [];
      for (let j = 0; j < teamSize; j++) {
        children.push({
          id: `${i + 1}-${j + 1}`,
          name: `${dept} Member ${j + 1}`,
          role: j === 0 ? 'Lead' : 'Member',
          department: dept,
        });
      }
      data.push({
        id: `${i + 1}`,
        name: `${dept} Team ${Math.floor(i / departments.length) + 1}`,
        role: 'Manager',
        department: dept,
        children,
      });
    }
    return data;
  }

  const allTopLevelNodes = generateTreeData(200);

  // Simulated data source — returns a page of top-level nodes with children embedded
  function createDataSource(pageSize: number) {
    return {
      async getRows(params: any) {
        // Simulate network latency
        await new Promise((r) => setTimeout(r, 300));

        let data = [...allTopLevelNodes];
        if (params.sortModel?.length) {
          const { field, direction } = params.sortModel[0];
          data.sort((a: any, b: any) => {
            const cmp = a[field] < b[field] ? -1 : a[field] > b[field] ? 1 : 0;
            return direction === 'asc' ? cmp : -cmp;
          });
        }

        const page = data.slice(params.startNode, params.endNode);
        return {
          rows: page,
          totalNodeCount: data.length,
        };
      },
    };
  }

  const columns = [
    { field: 'name', header: 'Name', sortable: true },
    { field: 'role', header: 'Role' },
    { field: 'department', header: 'Department', sortable: true },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(opts: Record<string, unknown>) {
    const pageSize = (opts.pageSize as number) ?? 20;
    grid.gridConfig = {
      columns,
      features: {
        serverSide: { pageSize },
        tree: {
          childrenField: 'children',
          animation: opts.animation === 'false' ? false : (opts.animation as string) ?? 'slide',
          defaultExpanded: opts.defaultExpanded as boolean ?? false,
        },
      },
    };

    grid.ready().then(() => {
      const serverSide = grid.getPluginByName('serverSide');
      serverSide?.setDataSource(createDataSource(pageSize));
      statusEl.textContent = 'Scroll down to load more nodes…';
    });
  }

  rebuild({ pageSize: 20, animation: 'slide', defaultExpanded: false });

  grid.on('datasource:loading' as any, (e: any) => {
    if (e.detail?.loading) {
      statusEl.textContent = 'Loading…';
    } else {
      const serverSide = grid.getPluginByName('serverSide') as any;
      if (serverSide) {
        const tree = grid.getPluginByName('tree') as any;
        const loaded = tree?.getFlattenedRows?.()?.length ?? '?';
        statusEl.textContent = `Loaded ${loaded} rows (${serverSide.getTotalRowCount() ?? '?'} top-level nodes total)`;
      }
    }
  });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues);
  }) as EventListener);
}
```

**Data flow:**
1. ServerSide fetches a block of top-level nodes → broadcasts `datasource:data`
2. TreePlugin claims the data and flattens it into the row model
3. Expand/collapse works locally for nodes with embedded children
4. For lazy children: TreePlugin queries `datasource:fetch-children` → ServerSide calls `getChildRows()` → broadcasts `datasource:children` → TreePlugin renders children

:::note
Child rows are fetched as a single batch — no pagination. If a tree node has many children, limit the response server-side.
:::

## Configuration Options

See [`TreeConfig`](./Interfaces/TreeConfig/) for the full list of options and defaults.

### Animation Options

The `animation` option controls how child nodes appear/disappear:

```ts
// Slide animation (default)
features: { tree: { animation: 'slide', ... } }

// Fade animation
features: { tree: { animation: 'fade', ... } }

// No animation
features: { tree: { animation: false, ... } }
```

:::note
Animation respects the grid-level `animation.mode` setting.
:::

### Tree Column

By default, the tree toggle and indentation appear on the first visible column. Use `treeColumn` to target a specific column — useful when combining with pinned columns or when the first column is narrow:

```ts
features: {
  tree: {
    treeColumn: 'name',      // Show tree toggle on the 'name' column
    childrenField: 'children',
  },
  pinnedColumns: true,
}
```

## Programmatic API

```ts
const plugin = grid.getPluginByName('tree');

plugin.expand(key);              // Expand a node by key
plugin.collapse(key);            // Collapse a node by key
plugin.toggle(key);              // Toggle a node's expanded state
plugin.expandAll();              // Expand all nodes
plugin.collapseAll();            // Collapse all nodes
plugin.expandToKey(key);         // Expand all ancestors to reveal a node
const keys = plugin.getExpandedKeys();   // Get currently expanded node keys
const expanded = plugin.isExpanded(key); // Check if a node is expanded
const rows = plugin.getFlattenedRows();  // Get flattened tree rows with metadata
const row = plugin.getRowByKey(key);     // Find a row by its key
```

## Events

```ts
// TreeEventsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/tree';

const container = document.getElementById('tree-events-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name' },
      { field: 'type', header: 'Type', width: 100 },
    ],
    features: {
      tree: { childrenField: 'children' },
    },
  };

  grid.rows = [
    {
      name: 'Engineering', type: 'Dept',
      children: [
        { name: 'Alice Johnson', type: 'Employee' },
        { name: 'Bob Smith', type: 'Employee' },
      ],
    },
    {
      name: 'Marketing', type: 'Dept',
      children: [
        { name: 'Carol White', type: 'Employee' },
      ],
    },
    {
      name: 'Sales', type: 'Dept',
      children: [
        { name: 'David Brown', type: 'Employee' },
        { name: 'Eve Davis', type: 'Employee' },
      ],
    },
  ];

  const log = container.querySelector('#tree-events-log');
  const clearBtn = container.querySelector('#clear-tree-events-log');

  function addLog(type: string, detail: string) {
    if (!log) return;
    const msg = document.createElement('div');
    msg.innerHTML = `<span class="event-type">[${type}]</span> ${detail}`;
    log.insertBefore(msg, log.firstChild);
    while (log.children.length > 15) log.lastChild?.remove();
  }

  clearBtn?.addEventListener('click', () => { if (log) log.innerHTML = ''; });

  grid.on('tree-expand', (d) => {
    addLog('tree-expand', `row ${d.rowIndex}, expanded: ${d.expanded}`);
  });
}
```

### tree-expand

Fired when a node is expanded or collapsed (via click, keyboard, `toggle()`, `expandAll()`, or `collapseAll()`):

```ts
grid.on('tree-expand', ({ key, row, expanded, depth, expandedKeys }) => {
  console.log(`${expanded ? 'Expanded' : 'Collapsed'} node ${key} at depth ${depth}`);
  console.log(`${expandedKeys?.length ?? 0} total nodes expanded`);
});
```

See [`TreeExpandDetail`](./Interfaces/TreeExpandDetail/) for the full event payload type.

## Styling

The tree plugin supports CSS custom properties for theming. Override these on `tbw-grid` or a parent container:

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-tree-toggle-size` | `1.25em` (~20px) | Toggle icon and spacer width |
| `--tbw-tree-indent-width` | `var(--tbw-tree-toggle-size)` | Indentation per level (must be ≥ toggle size) |
| `--tbw-tree-accent` | `var(--tbw-color-accent)` | Toggle icon hover color |
| `--tbw-animation-duration` | `200ms` | Expand/collapse animation |
| `--tbw-animation-easing` | `ease-out` | Animation curve |

:::note
`--tbw-tree-indent-width` defaults to `--tbw-tree-toggle-size` to ensure leaf nodes align with parent nodes. If you override indent width, ensure it's at least as wide as the toggle icon.
:::

### Example

```css
tbw-grid {
  /* Custom tree styling */
  --tbw-tree-toggle-size: 1.5em; /* Larger toggle icons */
  --tbw-tree-indent-width: 1.75em; /* Slightly wider indent */
  --tbw-tree-accent: #10b981;
  --tbw-animation-duration: 150ms;
}
```

### CSS Classes

The tree plugin uses these class names:

| Class | Element |
| --- | --- |
| `.tree-cell-wrapper` | Cell content wrapper with indentation |
| `.tree-expander` | Expander cell container |
| `.tree-toggle` | Expand/collapse icon |
| `.tree-spacer` | Indent spacer element |
| `.tbw-tree-slide-in` | Child row slide animation |
| `.tbw-tree-fade-in` | Child row fade animation |
| `.tbw-row-expanded` | Applied to a parent `.data-grid-row` while its children are visible. Use this for theming expanded rows instead of `[aria-expanded="true"]`. |

## Plugin Compatibility

:::caution[Incompatible Plugins]
The Tree plugin **cannot** be used with the following plugins:

- **[Row Grouping](/grid/plugins/grouping-rows.md)** — Both plugins transform the entire row model. Tree flattens nested hierarchies while Row Grouping groups flat rows with synthetic headers. Use one approach per grid.
- **[Pivot](/grid/plugins/pivot.md)** — Pivot replaces the entire row and column structure with aggregated pivot data. Tree hierarchy cannot coexist with pivot aggregation.
:::

A development-mode warning is shown if incompatible plugins are loaded together.

## See Also

- [Master-Detail](/grid/plugins/master-detail.md) — Expand rows to show nested detail grids
- [Server-Side Plugin](/grid/plugins/server-side.md) — Lazy-load child nodes from the server

---

# Undo/Redo Plugin

> Add undo/redo support for cell edits.

The Undo/Redo plugin tracks all cell edits and lets users revert or replay changes with familiar keyboard shortcuts (Ctrl+Z / Ctrl+Y). It maintains an in-memory history stack with configurable depth—perfect for data entry workflows where mistakes happen.

> ⚠️ **Required Dependency:** This plugin requires [EditingPlugin](/grid/plugins/editing.md) to be loaded first. UndoRedo tracks the edit history that EditingPlugin creates.

## Installation

```ts
import '@toolbox-web/grid/features/editing';
import '@toolbox-web/grid/features/undo-redo';
```

## Basic Usage

Enable both features and history tracking is automatic—every cell edit is recorded, and users can navigate back and forth through the edit history.

#### Angular

```typescript
// Feature imports - enable the [editing] and [undoRedo] inputs
import { GridEditingDirective } from '@toolbox-web/grid-angular/features/editing';
import { GridUndoRedoDirective } from '@toolbox-web/grid-angular/features/undo-redo';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-my-grid',
  imports: [Grid, GridEditingDirective, GridUndoRedoDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [editing]="true"
      [undoRedo]="{ maxHistorySize: 50 }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [...];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name', editable: true },
    { field: 'price', header: 'Price', type: 'number', editable: true },
    { field: 'quantity', header: 'Quantity', type: 'number', editable: true },
  ];
}
```

## Demo

Edit cells by double-clicking, then use Ctrl+Z / Ctrl+Y to undo/redo. Adjust the max history size with the control.

```ts
// UndoRedoDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/editing';
import '@toolbox-web/grid/features/undo-redo';

const container = document.getElementById('undo-redo-default-demo');
if (container) {
  const columns = [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name', editable: true },
    { field: 'quantity', header: 'Quantity', type: 'number', editable: true },
    { field: 'price', header: 'Price', type: 'number', editable: true },
  ];
  const sampleData = [
    { id: 1, name: 'Widget A', quantity: 10, price: 25.99 },
    { id: 2, name: 'Widget B', quantity: 5, price: 49.99 },
    { id: 3, name: 'Widget C', quantity: 20, price: 15.0 },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(maxHistorySize = 100) {
    grid.gridConfig = {
      columns,
      features: { editing: true, undoRedo: { maxHistorySize } },
    };
    grid.rows = [...sampleData];
  }

  rebuild();

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues.maxHistorySize as number);
  }) as EventListener);
}
```

## Configuration Options

See [`UndoRedoConfig`](./Interfaces/UndoRedoConfig/) for the full list of options and defaults.

## Keyboard Shortcuts

| Shortcut                              | Action |
| ------------------------------------- | ------ |
| `Ctrl+Z` / `Cmd+Z`                    | Undo   |
| `Ctrl+Y` / `Cmd+Y` / `Cmd+Shift+Z`   | Redo   |

## Programmatic API

```ts
const plugin = grid.getPluginByName('undoRedo');

plugin.undo();
plugin.redo();
const canUndo = plugin.canUndo();
const canRedo = plugin.canRedo();
plugin.clearHistory();
```

### Compound Actions (Transactions)

When a user edit cascades programmatic changes to other fields, group them into
a single undo step so Ctrl+Z reverts everything at once:

```ts
grid.on('cell-commit', () => {
  const undoRedo = grid.getPluginByName('undoRedo');
  undoRedo.beginTransaction();

  // Record cascaded updates manually
  const oldTotal = row.total;
  undoRedo.recordEdit(rowIndex, 'total', oldTotal, newTotal);
  grid.updateRow(rowId, { total: newTotal });

  // End after the auto-recorded original edit is captured
  queueMicrotask(() => undoRedo.endTransaction());
});
```

| Method              | Description                                         |
| ------------------- | --------------------------------------------------- |
| `beginTransaction()`| Start buffering edits into a compound group         |
| `endTransaction()`  | Finalize and push the compound as a single undo step|
| `recordEdit()`      | Manually record a cell edit (buffered during txn)   |

## Events

```ts
// UndoRedoEventsDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/editing';
import '@toolbox-web/grid/features/undo-redo';

const container = document.getElementById('undo-redo-events-demo');
if (container) {
  const grid = queryGrid('tbw-grid', container);

  grid.gridConfig = {
    columns: [
      { field: 'name', header: 'Name', editable: true },
      { field: 'department', header: 'Department', editable: true },
      { field: 'salary', header: 'Salary', type: 'number', editable: true },
    ],
    features: {
      editing: 'dblclick',
      undoRedo: true,
    },
  };

  grid.rows = [
    { name: 'Alice Johnson', department: 'Engineering', salary: 95000 },
    { name: 'Bob Smith', department: 'Marketing', salary: 75000 },
    { name: 'Carol White', department: 'Sales', salary: 68000 },
  ];

  const log = container.querySelector('#undo-redo-events-log');
  const clearBtn = container.querySelector('#clear-undo-redo-events-log');
  const undoBtn = container.querySelector('#undo-events-btn');
  const redoBtn = container.querySelector('#redo-events-btn');

  function addLog(type: string, detail: string) {
    if (!log) return;
    const msg = document.createElement('div');
    msg.innerHTML = `<span class="event-type">[${type}]</span> ${detail}`;
    log.insertBefore(msg, log.firstChild);
    while (log.children.length > 15) log.lastChild?.remove();
  }

  clearBtn?.addEventListener('click', () => { if (log) log.innerHTML = ''; });

  undoBtn?.addEventListener('click', () => {
    grid.getPluginByName('undoRedo')?.undo();
  });

  redoBtn?.addEventListener('click', () => {
    grid.getPluginByName('undoRedo')?.redo();
  });

  grid.on('undo', (d) => {
    addLog('undo', `field: ${d.field}, restored: "${d.oldValue}"`);
  });

  grid.on('redo', (d) => {
    addLog('redo', `field: ${d.field}, reapplied: "${d.value}"`);
  });
}
```

### undo / redo

Fired after an undo or redo action is applied:

```ts
grid.on('undo', ({ action, type }) => {
  console.log(`${type}: reverted ${action.field} on row ${action.rowIndex}`);
});

grid.on('redo', ({ action, type }) => {
  console.log(`${type}: reapplied ${action.field} on row ${action.rowIndex}`);
});
```

See [`UndoRedoDetail`](./Interfaces/UndoRedoDetail/) for the full event payload type.

## See Also

- **[Editing](/grid/plugins/editing.md)** — Inline cell editing (required)
- **[Clipboard](/grid/plugins/clipboard.md)** — Copy/paste cells

---

# Column Visibility Plugin

> Allow users to toggle column visibility via a panel.

The Visibility plugin gives users control over which columns are displayed. Hide less important columns by default, let users toggle them via a column chooser UI, or programmatically show/hide columns based on user preferences or screen size.

> 💡 **Optional Enhancement:** When [ReorderPlugin](/grid/plugins/reorder-columns.md) is also loaded, columns in the visibility panel become draggable for reordering. When [Column Grouping](/grid/plugins/grouping-columns.md) is also active, the panel shows columns in their actual display order, and fragmented groups (split across non-contiguous positions) appear as separate panel sections. Group headers in the panel are draggable and move only the columns in that fragment.

## Installation

```ts
import '@toolbox-web/grid/features/visibility';
```

## Basic Usage

Set `hidden: true` on columns you want hidden by default. The feature provides a UI and API for toggling column visibility at runtime.

#### Angular

```typescript
// Feature import - enables the [visibility] input
import { GridVisibilityDirective } from '@toolbox-web/grid-angular/features/visibility';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-configurable-grid',
  imports: [Grid, GridVisibilityDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [visibility]="true"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class ConfigurableGridComponent {
  rows = [];

  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'phone', header: 'Phone', hidden: true },
  ];
}
```

## Demo

Toggle the controls to explore hidden columns and locked columns. Click the column visibility icon in the header to open the panel.

```ts
// VisibilityDefaultDemo.astro
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/visibility';

const container = document.getElementById('visibility-default-demo');
if (container) {
  const allColumns = [
    { field: 'id', header: 'ID', type: 'number' as const },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'number' as const },
  ];

  const sampleData = [
    { id: 1, name: 'Alice', email: 'alice@example.com', department: 'Engineering', salary: 95000 },
    { id: 2, name: 'Bob', email: 'bob@example.com', department: 'Marketing', salary: 75000 },
    { id: 3, name: 'Carol', email: 'carol@example.com', department: 'Engineering', salary: 105000 },
    { id: 4, name: 'David', email: 'david@example.com', department: 'Sales', salary: 65000 },
    { id: 5, name: 'Eve', email: 'eve@example.com', department: 'HR', salary: 70000 },
  ];

  const grid = queryGrid('tbw-grid', container)!;

  function rebuild(opts: Record<string, unknown>) {
    const hiddenArr = (opts.hiddenColumns as string[]) ?? ['email'];
    const lockedArr = (opts.lockedColumns as string[]) ?? ['id'];

    grid.gridConfig = {
      columns: allColumns.map((col) => ({
        ...col,
        hidden: hiddenArr.includes(col.field),
        lockVisible: lockedArr.includes(col.field),
      })),
      features: { visibility: {} },
    };
    grid.rows = sampleData;
  }

  rebuild({ hiddenColumns: ['email'], lockedColumns: ['id'] });

  container.addEventListener('control-change', ((e: CustomEvent) => {
    rebuild(e.detail.allValues);
  }) as EventListener);
}
```

## Configuration Options

See [`VisibilityConfig`](./Interfaces/VisibilityConfig/) for the full list of options and defaults.

## Programmatic API

```ts
const plugin = grid.getPluginByName('visibility');

// Panel control
plugin.show();                          // Open the visibility panel
plugin.hide();                          // Close the panel
plugin.toggle();                        // Toggle panel open/closed
const open = plugin.isPanelVisible();   // Check if panel is open

// Column visibility
plugin.hideColumn('email');
plugin.showColumn('email');
plugin.toggleColumn('email');
plugin.showAll();                       // Show all hidden columns
plugin.setColumnVisible('email', false); // Set visibility directly
const isVis = plugin.isColumnVisible('email');

// Query state
const hidden = plugin.getHiddenColumns();   // List of hidden field names
const visible = plugin.getVisibleColumns(); // List of visible field names
const all = plugin.getAllColumns();          // Full column metadata with visibility
```

## Styling

The visibility panel supports CSS custom properties for theming. Override these on `tbw-grid` or a parent container:

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--tbw-visibility-hover` | `var(--tbw-color-row-hover)` | Row hover background |
| `--tbw-panel-padding` | `var(--tbw-spacing-md, 0.5rem)` | Panel content padding |
| `--tbw-panel-gap` | `var(--tbw-spacing-md, 0.5rem)` | Gap between items |
| `--tbw-menu-item-padding` | `0.375rem 0.25rem` | Row padding |
| `--tbw-font-size-sm` | `0.8125rem` | Label font size |
| `--tbw-font-size-2xs` | `0.625rem` | Drag handle size |
| `--tbw-color-fg-muted` | `#888` | Muted text (locked items) |
| `--tbw-border-radius` | `0.25em` | Row border radius |

### Example

```css
tbw-grid {
  /* Custom visibility panel styling */
  --tbw-visibility-hover: #e8f4fd;
  --tbw-panel-padding: 1rem;
  --tbw-panel-gap: 0.75rem;
}
```

### CSS Classes

The visibility panel uses these class names for advanced customization:

| Class | Element |
| --- | --- |
| `.tbw-visibility-content` | Panel container |
| `.tbw-visibility-list` | Scrollable column list |
| `.tbw-visibility-row` | Individual column row |
| `.tbw-visibility-row.locked` | Non-toggleable column |
| `.tbw-visibility-row.reorderable` | Can be dragged (with ReorderPlugin) |
| `.tbw-visibility-row.dragging` | Currently being dragged |
| `.tbw-visibility-row--grouped` | Column row inside a group section |
| `.tbw-visibility-group-header` | Group header row (with checkbox) |
| `.tbw-visibility-group-header.reorderable` | Draggable group header |
| `.tbw-visibility-handle` | Drag handle element |
| `.tbw-visibility-label` | Checkbox + text wrapper |

## See Also

- **[Column Reorder](../reorder-columns/)** — Drag-to-reorder columns
- **[Pinned Columns](/grid/plugins/pinned-columns.md)** — Sticky columns

---

# Plugin Development

> Build plugins that extend @toolbox-web/grid — lifecycle hooks, manifests, communication, feature registration, and bundling.

`@toolbox-web/grid` is **plugin-driven by design**. The core is intentionally minimal (rendering, virtualization, scheduling); selection, editing, filtering, grouping, drag-and-drop, validation, accessibility shortcuts — almost every grid capability is a plugin under `libs/grid/src/lib/plugins/`. The same APIs are available to you for building your own.

This section covers the plugin system from three angles:

  - [Architecture](/grid/plugin-development/architecture.md): How the plugin system works internally — lifecycle, hooks, render integration, the feature registry, and tree-shaking.
  - [Authoring Guide](/grid/plugin-development/custom-plugins.md): Step-by-step guide to building your first plugin: BaseGridPlugin, manifest, communication, queries, testing, distribution.
  - [API Reference](/grid/api/plugin-development/): Typed reference for BaseGridPlugin, GridPlugin, PluginManifest, hooks, and the feature registry.

## When to write a plugin

Reach for a plugin when you need to:

- React to grid lifecycle events (render, attach, detach, scroll, cell click, keyboard).
- Add new column-level or grid-level configuration that the grid validates and merges.
- Communicate with other plugins (e.g. an "audit log" plugin that listens for edits from `EditingPlugin`).
- Ship a reusable behaviour as its own package — third-party plugins are first-class.

For one-off styling or event handlers, plain CSS and `grid.addEventListener(...)` are usually enough — no plugin needed.

---

# Plugin Architecture

> How the @toolbox-web/grid plugin system works internally — lifecycle, hooks, communication, manifests, validated properties, and the feature registry.

This page describes how the plugin and feature subsystems work inside `@toolbox-web/grid`. It is the contributor-facing companion to the [Authoring Guide](/grid/plugin-development/custom-plugins.md) and to the typed [`BaseGridPlugin` API reference](/grid/api/plugin-development/classes/basegridplugin.md).

For grid-core internals (render scheduler, virtualization, DOM structure, configuration), see the main [Architecture](/grid/architecture.md) page.

## Plugin System

### Plugin Lifecycle

```mermaid
flowchart TB
    A["new Plugin()<br/><i>Constructor stores user config</i>"] --> B["attach(grid)<br/><i>Plugin receives grid ref, merges config</i>"]
    B --> C["Grid Render Cycle"]
    C --> D["User Interaction"]
    D --> E["detach()<br/><i>Cleanup on grid disconnect</i>"]

    subgraph C["Grid Render Cycle"]
        C1["processColumns() hook"]
        C2["processRows() hook"]
        C3["afterCellRender() hook (per cell)"]
        C4["afterRowRender() hook (per row)"]
        C5["afterRender() hook"]
    end

    subgraph D["User Interaction"]
        D1["onCellClick() hook"]
        D2["onKeyDown() hook"]
        D3["onScroll() hook"]
        D4["onCellMouseDown/Move/Up()"]
    end
```

### Creating a Plugin

```typescript
import { BaseGridPlugin, CellClickEvent, type GridElement } from '@toolbox-web/grid';
import styles from './my-plugin.css?inline';

interface MyPluginConfig {
  enabled?: boolean;
}

export class MyPlugin extends BaseGridPlugin<MyPluginConfig> {
  readonly name = 'myPlugin';
  override readonly styles = styles;

  protected override get defaultConfig(): Partial<MyPluginConfig> {
    return { enabled: true };
  }

  override attach(grid: GridElement): void {
    super.attach(grid); // MUST call super
    // Setup listeners with this.disconnectSignal for auto-cleanup
  }

  override afterRender(): void {
    if (!this.config.enabled) return;
    // Access DOM via this.gridElement
  }

  override onCellClick(event: CellClickEvent): boolean | void {
    // Return true to prevent default behavior
  }
}
```

### Plugin Communication

Plugins communicate via three channels:

**Event Bus** (plugin-to-plugin notifications):

```typescript
// Listen for events from other plugins
this.on('selection-cleared', (detail) => { /* ... */ });

// Emit to other plugins only
this.emitPluginEvent('selection-cleared', { source: 'keyboard' });

// Emit to both plugins AND external addEventListener consumers
this.broadcast('sort-change', { sortModel: [...this.sortModel] });
```

**Query System** (sync state retrieval):

```typescript
// Declare queryable state in manifest
static override readonly manifest = {
  queries: [{ type: 'canMoveColumn', description: 'Check movability' }],
};

// Handle queries
override handleQuery(query: PluginQuery): unknown {
  if (query.type === 'canMoveColumn') return !column.pinned;
  return undefined;
}

// Query from another plugin
const responses = this.grid.query<boolean>('canMoveColumn', column);
```

### Plugin Manifest

Plugins declare owned config properties via a static `manifest`:

```typescript
import type { PluginManifest } from '@toolbox-web/grid';

static override readonly manifest: PluginManifest<EditingConfig> = {
  ownedProperties: [
    { property: 'editable', level: 'column', description: 'the "editable" column property' },
    { property: 'editor',   level: 'column', description: 'the "editor" column property' },
  ],
  configRules: [
    {
      id: 'editing/invalid-edit-on',
      severity: 'warn',
      message: '"editOn: dblclick" has no effect when editable is false',
      check: (config) => config.editOn === 'dblclick' && config.editable === false,
    },
  ],
};
```

See the [Custom Plugins guide → Plugin Manifest](/grid/plugin-development/custom-plugins.md#plugin-manifest) for the full schema (queries, events, incompatibleWith, hookPriority).

The grid validates at runtime that properties like `editable: true` are only used when the owning plugin is loaded, and provides helpful error messages with import hints.

### Validated Properties

| Property       | Required Plugin         | Level  |
| -------------- | ----------------------- | ------ |
| `editable`     | `EditingPlugin`         | Column |
| `editor`       | `EditingPlugin`         | Column |
| `editorParams` | `EditingPlugin`         | Column |
| `group`        | `GroupingColumnsPlugin` | Column |
| `pinned`       | `PinnedColumnsPlugin`   | Column |
| `columnGroups` | `GroupingColumnsPlugin` | Config |

Validation runs in the `RenderScheduler.mergeConfig` callback, **after** plugins are initialized. Error messages clearly state which plugin is missing and how to import it.

### Hook performance budget

Every plugin hook runs in the grid's hot path. Keep this table in mind when implementing them — work that's cheap per cell becomes expensive when you multiply it by the number of visible cells and the frequency of scroll events.

| Hook | When it runs | Impact | Rule of thumb |
|------|-------------|--------|---------------|
| `processColumns()` | Every data/config update | Low | Runs once per update — fine for non-trivial work |
| `processRows()` | Every data update | Medium | Runs over full dataset — `O(n)` work is OK, `O(n²)` is not |
| `afterCellRender()` | Every visible cell, every scroll frame | **High** | Keep < 0.1 ms per call; no DOM queries, no allocations |
| `afterRowRender()` | Every visible row, every scroll frame | **High** | Same budget as cells; cache anything reusable in `processRows()` |
| `afterRender()` | Every render cycle | Medium | Avoid DOM queries; use cached refs from earlier hooks |

**Profiling slow plugins:** open Chrome DevTools → Performance, record a scroll, and look for your plugin name in the flame chart. Work that consistently shows up in `afterCellRender` / `afterRowRender` should usually move to `processRows()` and be cached.

### Style injection

Plugins must not append `<style>` elements as children of `<tbw-grid>` — they get removed by `replaceChildren()` on the next render. Use one of:

```ts
// ✅ The `styles` property (recommended for plugins — adopted into the grid's stylesheets)
override readonly styles = `
  .my-class { color: blue; }
`;

// ✅ registerStyles for runtime-injected / dynamic CSS
this.gridElement.registerStyles('my-id', '.my-class { color: blue; }');

// ✅ Standard global CSS also works (stylesheet, <style> in <head>)

// ❌ Child <style> nodes inside the grid are wiped on render
const style = document.createElement('style');
this.gridElement.appendChild(style);
```

### Wrapping plugins (host-DOM chrome)

Most plugins **enrich** the grid: they tag rows in `processRows()`, decorate cells in
`afterCellRender()`, or handle interaction hooks. A few plugins instead **wrap** the grid —
they take the freshly built grid DOM and render their own chrome (a header bar, a sidebar,
a toolbar) _around_ it. The [Shell plugin](/grid/plugins/shell.md) is the canonical example.

Wrapping is not done with the per-cell/per-row hooks. It uses one dedicated lifecycle hook:

```typescript
override afterStructuralRender(): void {
  const root = this.grid?._renderRoot;
  if (!root || root.querySelector('.my-chrome > .tbw-grid-content')) return;
  // 1. Core has built a BARE grid containing `.tbw-grid-content`.
  // 2. Relocate that existing node into your chrome — do NOT re-create it.
  //    Moving (not rebuilding) preserves the content subtree, its event
  //    listeners, and the grid's cached DOM refs.
  const content = root.querySelector('.tbw-grid-content');
  const chrome = buildChrome(); // header bar + body + sidebar, etc.
  chrome.querySelector('[data-content-slot]')!.append(content!);
  root.append(chrome);
}
```

Key contract for a wrapping plugin:

- **Use `afterStructuralRender()`, not `afterRender()`.** It fires synchronously inside the
  same task as the structural DOM build, before paint — so there is no flash of unwrapped
  content. It runs only on full structural rebuilds (connect / structural change), **never**
  on the scroll or data hot path.
- **Move the `.tbw-grid-content` node; never replace it.** The grid caches references into
  that subtree (body, viewport, rows). Re-creating it breaks scrolling, virtualization, and
  every plugin that cached a ref. Relocate the existing element into your wrapper.
- **Be idempotent.** A full rebuild discards whatever chrome a previous invocation produced,
  so re-create it each time and early-return when the desired structure is already present.
- **Render your own content after wrapping.** Inject titles, toolbar buttons, and panel
  bodies into the chrome you built — query them from `this.grid._renderRoot`, not from the
  grid-body refs (which point inside `.tbw-grid-content`).

See [`afterStructuralRender` in the `BaseGridPlugin` reference](/grid/api/plugin-development/classes/basegridplugin.md)
for the full hook contract.

---

## Feature Registry

The **features API** is the recommended way to enable grid capabilities. It wraps the plugin system with declarative configuration and tree-shakeable side-effect imports.

### Why Features?

| Aspect | Features (recommended) | Plugins (advanced) |
|--------|----------------------|--------------------|
| API | `features: { selection: 'row' }` | `plugins: [new SelectionPlugin({ mode: 'row' })]` |
| Import | `import '@toolbox-web/grid/features/selection'` | `import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection'` |
| Dependencies | Auto-resolved | Manual ordering |
| Tree-shaking | Zero cost if unused | Must avoid importing unused plugins |

### How It Works

Each feature module is a side-effect import that registers a factory function:

```mermaid
flowchart LR
    subgraph imports["SIDE-EFFECT IMPORTS"]
        A["import '.../features/selection'"]
        B["import '.../features/editing'"]
    end

    A -->|"module executes"| C["registerFeature('selection', factory)"]
    B -->|"module executes"| D["registerFeature('editing', factory)"]

    C --> E["featureRegistry<br/><i>Map&lt;string, factory&gt;</i>"]
    D --> E

    F["gridConfig.features"] --> G["createPluginsFromFeatures()"]
    E --> G
    G --> H["Plugin instances<br/>(ordered by dependencies)"]
```

### Registration

When a feature module is imported, it runs immediately at load time:

```typescript
// libs/grid/src/lib/features/selection.ts
import { SelectionPlugin } from '../plugins/selection';
import { registerFeature } from './registry';

registerFeature('selection', (config) => {
  // Shorthand strings → full config
  if (config === 'cell' || config === 'row' || config === 'range') {
    return new SelectionPlugin({ mode: config });
  }
  return new SelectionPlugin(config ?? undefined);
});
```

Each factory handles **shorthand values** (e.g., `'row'` → `{ mode: 'row' }`), so users get a simpler API.

### Lazy Hook Design

The grid core never references the feature registry directly. Instead, a **hook function** bridges them:

```typescript
// feature-hook.ts — imported by grid core
export let resolveFeatures: FeatureResolverFn | undefined;  // Starts undefined!

// registry.ts — imported only when a feature is imported
setFeatureResolver(createPluginsFromFeatures);  // Sets the hook
```

If no feature modules are imported, `resolveFeatures` stays `undefined` — the entire registry module is tree-shaken away by the bundler. This is why features are zero-cost when unused.

### Resolution Flow

During plugin initialization:

```typescript
// grid.ts — #initializePlugins()
const features = this.#effectiveConfig?.features;
if (features && resolveFeatures) {
  featurePlugins = resolveFeatures(features);
}
// Feature plugins ordered first, then explicit plugins
const allPlugins = [...featurePlugins, ...explicitPlugins];
```

Dependencies are auto-ordered: `selection` and `editing` always instantiate first, since other plugins (like `clipboard` or `undoRedo`) depend on them.

### Tree-Shaking

Feature modules are marked as side-effects in `package.json`:

```json
{ "sideEffects": ["./lib/features/*.js"] }
```

This tells bundlers: "these imports have side effects (registration), don't optimize them away." But un-imported features are never loaded, so only the features you use add to bundle size (~200–300 bytes each).

## See Also

- **[Authoring Guide](/grid/plugin-development/custom-plugins.md)** — Step-by-step plugin tutorial with complete examples.
- **[Plugin Development API](/grid/api/plugin-development/classes/basegridplugin.md)** — Typed reference for `BaseGridPlugin`, `GridPlugin`, `PluginManifest`.
- **[Grid Architecture](/grid/architecture.md)** — Render scheduler, virtualization, and DOM structure that plugins integrate with.
- **[Framework Adapters](/grid/framework-adapters.md)** — How React / Angular / Vue adapters extend the plugin pipeline.

---

# Custom Plugins

> Build custom plugins for @toolbox-web/grid — lifecycle hooks, communication, queries, manifests, testing, and complete examples.

Learn how to extend `@toolbox-web/grid` with your own plugins. Plugins can add new features, modify data, inject styles, and respond to user interactions.

## Plugin Architecture

All plugins extend [`BaseGridPlugin`](/grid/api/plugin-development/classes/basegridplugin.md) and implement lifecycle hooks:

```mermaid
flowchart TB
    A["attach()<br/><i>Called when plugin is added to grid</i>"]
    B["processColumns()<br/><i>Transform column definitions</i>"]
    C["processRows()<br/><i>Transform row data</i>"]

    subgraph render["For each visible row"]
        direction TB
        D["afterCellRender()<br/><i>Per-cell hook (called for each cell)</i>"]
        E["afterRowRender()<br/><i>Per-row hook (after all cells in row)</i>"]
        D --> E
    end

    F["afterRender()<br/><i>Grid-wide DOM manipulation</i>"]
    G["User Interactions<br/><i>onCellClick, onKeyDown, etc.</i>"]
    H["detach()<br/><i>Cleanup when plugin is removed</i>"]

    A --> B --> C --> render --> F --> G --> H
```

## Basic Plugin Structure

A typical plugin lives in a folder under `libs/grid/src/lib/plugins/`:

  - my-feature/
    - my-feature-plugin.ts — Plugin class extending [`BaseGridPlugin`](/grid/api/plugin-development/classes/basegridplugin.md)
    - my-feature-plugin.spec.ts — Co-located unit tests
    - my-feature.css — Plugin styles (optional)
    - types.ts — Public config/event types (optional)
    - index.ts — Barrel export

```typescript
import { BaseGridPlugin, type AfterCellRenderContext } from '@toolbox-web/grid';

// 1. Define your config interface
interface HighlightConfig {
  field: string;
  threshold: number;
  className?: string;
}

// 2. Extend BaseGridPlugin with your config type
export class HighlightPlugin extends BaseGridPlugin<HighlightConfig> {
  // Required: unique plugin name
  readonly name = 'highlight';

  // Optional: CSS styles to inject
  override readonly styles = `
    .highlight-cell {
      background: linear-gradient(135deg, #fff3cd, #ffeeba);
      font-weight: 600;
    }
  `;

  // Called for each cell during rendering
  override afterCellRender(context: AfterCellRenderContext): void {
    const { field, threshold, className = 'highlight-cell' } = this.config;
    const { column, value, cellElement } = context;

    if (column.field !== field) return;

    const numValue = typeof value === 'number' ? value : parseFloat(String(value));
    if (!isNaN(numValue) && numValue > threshold) {
      cellElement.classList.add(className);
    }
  }
}
```

## Using Your Plugin

```typescript
import { HighlightPlugin } from './highlight-plugin';

grid.gridConfig = {
  columns: [...],
  plugins: [
    new HighlightPlugin({
      field: 'salary',
      threshold: 100000,
      className: 'high-earner',
    }),
  ],
};
```

## Lifecycle Hooks

### `attach(grid)`

Called when the plugin is attached to the grid. Use for initial setup.

```typescript
import type { GridElement } from '@toolbox-web/grid';

override attach(grid: GridElement): void {
  super.attach(grid); // Always call super first!
  this.state = new Map();
  console.log('Attached to grid with', grid.rows.length, 'rows');
}
```

### `detach()`

Called when the plugin is removed. Clean up event listeners, timers, etc.

```typescript
override detach(): void {
  this.state.clear();
  clearInterval(this.timer);
  super.detach(); // Always call super last!
}
```

### `processColumns(columns)`

Transform column definitions before rendering. Return the modified array.

```typescript
override processColumns(columns: ColumnConfig[]): ColumnConfig[] {
  return [
    ...columns,
    {
      field: '__rowNumber',
      header: '#',
      width: 50,
      renderer: (ctx) => String(ctx.rowIndex + 1),
    },
  ];
}
```

### `processRows(rows)`

Transform row data before rendering. Return the modified array.

```typescript
override processRows(rows: T[]): T[] {
  return rows.filter(row => row.active);
}
```

### `afterRender()`

Called after each render cycle. Use for grid-wide DOM manipulation.

```typescript
override afterRender(): void {
  const gridEl = this.gridElement;
  const rows = gridEl.querySelectorAll('.data-grid-row');
  rows.forEach((row, i) => {
    if (i % 2 === 0) row.classList.add('even-row');
  });
}
```

### `afterCellRender(context)`

Called after each cell is rendered. More efficient than `afterRender` for per-cell modifications because you receive the cell context directly—no DOM queries needed.

```typescript
import type { AfterCellRenderContext } from '@toolbox-web/grid';

override afterCellRender(context: AfterCellRenderContext): void {
  const { row, rowIndex, colIndex, value, cellElement, column } = context;

  // Add selection class without DOM queries
  if (this.isSelected(rowIndex, colIndex)) {
    cellElement.classList.add('selected');
  }

  // Add validation error styling
  if (this.hasError(row, column.field)) {
    cellElement.classList.add('has-error');
  }
}
```

:::note[Performance]
`afterCellRender` is called for every visible cell during render and scroll. Keep implementation fast.
:::

### `afterRowRender(context)`

Called after a row is fully rendered (all cells complete). Use for row-level decorations, styling, or ARIA attributes.

```typescript
import type { AfterRowRenderContext } from '@toolbox-web/grid';

override afterRowRender(context: AfterRowRenderContext): void {
  const { row, rowIndex, rowElement } = context;

  // Add row selection class without DOM queries
  if (this.isRowSelected(rowIndex)) {
    rowElement.classList.add('selected', 'row-focus');
  }

  // Add validation error styling
  if (this.rowHasErrors(row)) {
    rowElement.classList.add('has-errors');
  }
}
```

:::note[Performance]
`afterRowRender` is called for every visible row during render and scroll. Keep implementation fast.
:::

## Built-in Plugin Helpers

[`BaseGridPlugin`](/grid/api/plugin-development/classes/basegridplugin.md) provides protected helpers:

| Helper | Description |
|--------|-------------|
| `this.grid` | Typed `GridElement` (extends `GridElementRef`) |
| `this.gridElement` | Grid as `HTMLElement` for DOM queries |
| `this.columns` | Current column configurations |
| `this.visibleColumns` | Only visible columns |
| `this.rows` | Processed rows (after filtering, grouping) |
| `this.sourceRows` | Original unfiltered rows |
| `this.disconnectSignal` | `AbortSignal` for auto-cleanup |
| `this.isAnimationEnabled` | Whether animations are enabled |
| `this.animationDuration` | Animation duration in ms |
| `this.gridIcons` | Merged icon configuration |
| `this.getPluginByName(name)` | Get another plugin by name (preferred) |
| `this.getPlugin(PluginClass)` | Get another plugin by class (alternative) |
| `this.emit(eventName, detail)` | Dispatch a DOM `CustomEvent` from the grid (external consumers) |
| `this.broadcast(eventType, detail)` | Emit on the internal event bus + DOM (other plugins + external consumers) |
| `this.on(eventType, callback)` | Subscribe to event-bus events (auto-cleaned on detach) |
| `this.requestRender()` | Request full re-render |
| `this.requestAfterRender()` | Request lightweight style update |
| `this.requestVirtualRefresh()` | Re-render visible rows without rebuilding the row model |
| `this.setIcon(el, iconKey)` | Set icon on element using CSS-first hybrid approach |

## Event Hooks

### `onCellClick(event)`

Handle cell click events. Return `true` to prevent default behavior.

```typescript
import type { CellClickEvent } from '@toolbox-web/grid';

override onCellClick(event: CellClickEvent): boolean | void {
  const { row, field, value, cellEl } = event;
  if (field === 'delete') {
    this.handleDelete(row);
    return true; // Prevent default click handling
  }
  return false; // Allow normal processing
}
```

### `onCellMouseDown(event)`

Handle mousedown for drag operations or selection.

```typescript
import type { CellMouseEvent } from '@toolbox-web/grid';

override onCellMouseDown(event: CellMouseEvent): boolean | void {
  const { row, field } = event;

  if (field === 'drag-handle') {
    this.startDrag(row);
    return true;
  }

  return false;
}
```

### `onKeyDown(event)`

Handle keyboard events. Return `true` to prevent default.

```typescript
override onKeyDown(event: KeyboardEvent): boolean | void {
  if (event.ctrlKey && event.key === 'd') {
    this.duplicateSelectedRow();
    return true;
  }
  return false;
}
```

### `onScroll(event)`

Respond to scroll events (use sparingly — can impact performance).

```typescript
import type { ScrollEvent } from '@toolbox-web/grid';

override onScroll(event: ScrollEvent): void {
  this.updateStickyElements(event.scrollTop);
}
```

### `renderRow(row, rowEl, rowIndex)`

Custom row rendering. Return `true` to skip default rendering.

```typescript
override renderRow(row: T, rowEl: HTMLElement, rowIndex: number): boolean | void {
  if (row.type === 'section-header') {
    rowEl.innerHTML = `<div class="section-header">${row.title}</div>`;
    return true;
  }
  return false;
}
```

## Injecting Styles

Plugins can inject CSS via the `styles` property (uses `adoptedStyleSheets`):

#### External CSS File

```typescript
// Import CSS as string (Vite)
import styles from './my-plugin.css?inline';

export class MyPlugin extends BaseGridPlugin {
  override readonly styles = styles;
}
```

```css
/* my-plugin.css */
.my-custom-class {
  background: #f0f0f0;
  border-left: 3px solid #1976d2;
}
```

#### Inline Styles

```typescript
export class MyPlugin extends BaseGridPlugin {
  override readonly styles = `
    .my-custom-class {
      background: #f0f0f0;
      border-left: 3px solid #1976d2;
    }

    .my-custom-class:hover {
      background: #e0e0e0;
    }
  `;
}
```

:::caution
Do not append `<style>` elements as **children of `<tbw-grid>`** — the grid calls `replaceChildren()` during renders, which removes child nodes. For plugin styles, use the `styles` property (shown above) or `this.gridElement.registerStyles(id, css)`. Note: external CSS (stylesheets, `<style>` in `<head>`) is unaffected and works normally since the grid uses light DOM.
:::

## Accessing Grid State

```typescript
override afterRender(): void {
  // Access current rows (after processing)
  const rows = this.grid.rows;

  // Access effective config
  const config = this.grid.gridConfig;

  // Access sort state
  const sortState = this.grid.sortState;

  // Access changed rows (editing)
  const changes = this.grid.changedRows;

  // Request a full re-render (internal API for plugins)
  this.grid.requestRender();

  // Request only afterRender hooks (lightweight update)
  this.grid.requestAfterRender();
}
```

## Plugin Manifest

The **Plugin Manifest** is a static property that declares metadata about your plugin's capabilities and requirements. The grid uses this metadata for:

- **Validation**: Detect missing plugins when their properties are used
- **Configuration rules**: Warn or error on invalid config combinations
- **Query routing**: Efficiently route queries only to plugins that handle them
- **Event discovery**: Document events that other plugins can subscribe to
- **Incompatibility detection**: Warn when conflicting plugins are loaded together

### Manifest Structure

```typescript
import { BaseGridPlugin, type PluginManifest } from '@toolbox-web/grid';

interface MyPluginConfig {
  optionA?: boolean;
  optionB?: boolean;
}

export class MyPlugin extends BaseGridPlugin<MyPluginConfig> {
  static override readonly manifest: PluginManifest<MyPluginConfig> = {
    // Properties this plugin owns (for validation)
    ownedProperties: [
      {
        property: 'myColumnProp',
        level: 'column',
        description: 'the "myColumnProp" column property',
      },
      {
        property: 'myGridOption',
        level: 'config',
        description: 'the "myGridOption" grid config option',
      },
    ],

    // Configuration validation rules
    configRules: [
      {
        id: 'my-plugin/invalid-combo',
        severity: 'warn',
        message: 'optionA and optionB cannot both be true',
        check: (config) => config.optionA === true && config.optionB === true,
      },
    ],

    // Queries this plugin handles
    queries: [
      { type: 'getMyState', description: 'Get the current plugin state' },
    ],

    // Events this plugin emits
    events: [
      { type: 'my-state-change', description: 'Emitted when state changes' },
    ],

    // Plugins that conflict with this one
    incompatibleWith: [
      { name: 'conflictingPlugin', reason: 'Both plugins modify the same DOM elements' },
    ],

    // Hook execution priority (lower = earlier, default 0)
    hookPriority: {
      processRows: 100,   // Run after most plugins
      afterRender: -50,   // Run before most plugins
    },
  };

  readonly name = 'myPlugin';
}
```

### Owned Properties

Declare properties your plugin adds to [`ColumnConfig`](/grid/api/core/interfaces/columnconfig.md) or [`GridConfig`](/grid/api/core/interfaces/gridconfig.md). If a user configures these properties without loading your plugin, the grid throws a helpful error:

```typescript
ownedProperties: [
  {
    property: 'editable',
    level: 'column',
    description: 'the "editable" column property',
    importHint: "import { EditingPlugin } from '@toolbox-web/grid/plugins/editing';",
  },
],
```

Error shown to user:

```
[tbw-grid] Configuration error:
Column(s) [name, email] use the "editable" column property, but the required plugin is not loaded.
  → Add the plugin to your gridConfig.plugins array:
    import { EditingPlugin } from '@toolbox-web/grid/plugins/editing';
    plugins: [new EditingPlugin(), ...]
```

### Configuration Rules

```typescript
configRules: [
  {
    id: 'selection/range-dblclick',
    severity: 'warn',
    message: '"triggerOn: dblclick" has no effect when mode is "range".',
    check: (config) => config.mode === 'range' && config.triggerOn === 'dblclick',
  },
],
```

- `severity: 'error'` — Throws an exception (always)
- `severity: 'warn'` — Logs to console (development only)

### Hook Priority

By default, hooks execute in plugin array order. Use `hookPriority` to override the execution order for specific hooks without changing the plugin array:

```typescript
static override readonly manifest: PluginManifest = {
  hookPriority: {
    processRows: 100,   // Higher value → runs later
    afterRender: -50,   // Negative value → runs earlier
  },
};
```

- Default priority is **0** for all hooks
- **Lower values** execute first; **higher values** execute later
- Plugins with equal priority preserve their original array order
- Priority is configured **per hook** — a plugin can run early for one hook and late for another

Available hooks: `processColumns`, `processRows`, `afterRender`, `afterCellRender`, `afterRowRender`, `onHeaderClick`, `onRowClick`, `onCellClick`, `onCellMouseDown`, `onCellMouseMove`, `onCellMouseUp`, `onKeyDown`, `onScroll`, `onScrollRender`.

### Plugin Dependencies

Declare required plugins via a static `dependencies` property:

```typescript
export class UndoRedoPlugin extends BaseGridPlugin<UndoRedoConfig> {
  static override readonly dependencies: PluginDependency[] = [
    { name: 'editing', required: true, reason: 'Tracks cell edit history' },
    { name: 'selection', required: false, reason: 'Enables selection-based undo' },
  ];

  readonly name = 'undoRedo';
}
```

:::danger
When using the manual `plugins` array, dependencies must be loaded *before* the dependent plugin. Wrong order **throws a runtime error**:

```typescript
// ✅ Correct order
plugins: [new EditingPlugin(), new UndoRedoPlugin()]

// ❌ Wrong order — throws error
plugins: [new UndoRedoPlugin(), new EditingPlugin()]
```
:::

:::tip
The **features API** handles dependency ordering automatically. When you use `features: { ... }`, the grid reorders plugins based on declared dependencies — no manual ordering required, and import order doesn't matter (safe from Prettier's alphabetical sorting).

```typescript
// Order doesn't matter — the grid resolves dependencies for you
import '@toolbox-web/grid/features/undo-redo';
import '@toolbox-web/grid/features/editing';

grid.gridConfig = {
  features: { editing: true, undoRedo: true },
};
```
:::

#### Conditional dependencies and severity

A dependency can be made **config-conditional** with a `when` predicate, and its missing-dependency behavior tuned with `severity`:

```typescript
export class PivotPlugin extends BaseGridPlugin<PivotConfig> {
  static override readonly dependencies: PluginDependency[] = [
    {
      name: 'shell',
      // Only needed when the tool panel is enabled
      required: false,
      when: (cfg) => (cfg as PivotConfig).showToolPanel === true,
      severity: 'warn',
      reason: 'PivotPlugin needs a tool-panel host when showToolPanel is enabled',
    },
  ];

  readonly name = 'pivot';
}
```

- **`when(pluginConfig)`** — receives the depending plugin's resolved config (defaults merged with user config) and is evaluated **before** the plugin attaches. Return `false` to skip the dependency entirely. When omitted, the dependency always applies.
- **`severity`** — overrides the default derived from `required`:
  - `'error'` — throws and halts grid setup (the default when `required` is not `false`).
  - `'warn'` — logs a `console.warn` and continues (development only).
  - `'info'` — logs a verbose `console.debug` and continues (development only).

When `severity` is omitted, a missing **hard** dependency (`required !== false`) throws and a missing **soft** dependency (`required: false`) stays silent — preserving backward-compatible behavior. Opt into a message by setting `severity` explicitly.

## Plugin Communication

### Event Bus (Plugin-to-Plugin)

Plugins can emit and subscribe to events using the built-in Event Bus. Events are automatically cleaned up when a plugin is detached.

```typescript
import { BaseGridPlugin, type PluginManifest } from '@toolbox-web/grid';

// Plugin A: Emit events
export class FilterPlugin extends BaseGridPlugin<FilterConfig> {
  readonly name = 'filtering';

  // Declare events in manifest for discoverability
  static override readonly manifest: PluginManifest = {
    events: [
      { type: 'filter-change', description: 'Emitted when filters change' },
    ],
  };

  applyFilter(criteria: FilterCriteria): void {
    // ... filter logic

    // Broadcast to both DOM consumers and other plugins
    this.broadcast('filter-change', { criteria, rowCount: this.rows.length });
  }
}

// Plugin B: Subscribe to events
export class SelectionPlugin extends BaseGridPlugin<SelectionConfig> {
  readonly name = 'selection';

  override attach(grid: GridElement): void {
    super.attach(grid);

    // Subscribe — auto-cleaned on detach
    this.on('filter-change', (detail) => {
      console.log('Filter changed, clearing selection');
      this.clearSelection();
    });
  }
}
```

### Query System (Synchronous State Retrieval)

Plugins can expose queryable state that other plugins can retrieve synchronously.

```typescript
import { BaseGridPlugin, type PluginManifest, type PluginQuery } from '@toolbox-web/grid';

// Plugin A: Handle queries
export class SelectionPlugin extends BaseGridPlugin<SelectionConfig> {
  readonly name = 'selection';

  // Declare queries in manifest for routing
  static override readonly manifest: PluginManifest = {
    queries: [
      { type: 'getSelection', description: 'Get current selection state' },
    ],
  };

  override handleQuery(query: PluginQuery): unknown {
    if (query.type === 'getSelection') {
      return this.getSelection();
    }
    return undefined;
  }
}

// Plugin B: Query other plugins
export class ClipboardPlugin extends BaseGridPlugin<ClipboardConfig> {
  readonly name = 'clipboard';

  copy(): void {
    const responses = this.grid.query<SelectionResult>('getSelection', undefined);
    const selection = responses[0];
    if (selection?.ranges.length > 0) {
      // Copy selected cells
    }
  }
}
```

### DOM Events (External Consumers)

For events that external code should listen to, use `emit()`:

```typescript
this.emit('copy', { text: copiedText, rowCount: 5 });

// External code:
grid.on('copy', (detail) => console.log(detail));
```

## TypeScript Generics

For type-safe row access, use generics:

```typescript
export class TypedPlugin<T extends { id: number }> extends BaseGridPlugin<{ idField: keyof T }> {
  override processRows(rows: T[]): T[] {
    const idField = this.config.idField;
    return rows.filter(row => row[idField] != null);
  }
}

// Usage
new TypedPlugin<Employee>({ idField: 'employeeId' });
```

## Complete Example: Row Numbering Plugin

This example adds a synthetic column that doesn't map to any field in the data. The `__rowNumber` field doesn't exist on row objects—the renderer uses `ctx.rowIndex` instead of `ctx.value`. This pattern is safe because:

- `processColumns` only modifies column definitions, not row data
- Renderers produce DOM output—they don't write back to the source data
- The `rows` array remains unchanged

```typescript
import { BaseGridPlugin, type ColumnConfig } from '@toolbox-web/grid';

interface RowNumberConfig {
  header?: string;
  width?: number;
  startFrom?: number;
}

export class RowNumberPlugin extends BaseGridPlugin<RowNumberConfig> {
  readonly name = 'rowNumber';

  override readonly styles = `
    .row-number-cell {
      color: #888;
      font-size: 0.85em;
      text-align: center;
    }
  `;

  override processColumns(columns: ColumnConfig[]): ColumnConfig[] {
    const { header = '#', width = 50, startFrom = 1 } = this.config;

    return [
      {
        field: '__rowNumber',
        header,
        width,
        minWidth: 40,
        maxWidth: 80,
        resizable: false,
        sortable: false,
        renderer: (ctx) => {
          const span = document.createElement('span');
          span.className = 'row-number-cell';
          span.textContent = String(ctx.rowIndex + startFrom);
          return span;
        },
      },
      ...columns,
    ];
  }
}
```

## Best Practices

1. **Always call `super`** — In `attach()` call it first, in `detach()` call it last
2. **Use unique names** — Plugin `name` should be unique across all plugins
3. **Clean up resources** — Remove event listeners and timers in `detach()`
4. **Return modified data** — `processColumns` and `processRows` must return arrays
5. **Use `ctx.signal`** — For automatic cleanup of event listeners in renderers
6. **Avoid heavy operations** — Keep hooks fast, especially `onScroll` and `afterRender`
7. **Document your config** — Use JSDoc comments for IDE support
8. **Version your plugins** — Increment version when making breaking changes

## Testing Plugins

```typescript
import { describe, it, expect, beforeEach } from 'vitest';
import { RowNumberPlugin } from './row-number-plugin';

describe('RowNumberPlugin', () => {
  let plugin: RowNumberPlugin;

  beforeEach(() => {
    plugin = new RowNumberPlugin({ startFrom: 1 });
  });

  it('should add row number column', () => {
    const columns = plugin.processColumns([
      { field: 'name', header: 'Name' },
    ]);

    expect(columns).toHaveLength(2);
    expect(columns[0].field).toBe('__rowNumber');
  });
});
```

## Registering as a Feature

Plugins can be promoted to **features** so consumers can enable them via the declarative `features` config instead of manually instantiating classes. This also enables shorthand syntax and tree-shaking.

### 1. Create the Feature Module

Create a feature file that registers your plugin with a factory function:

```typescript
// my-feature.ts (e.g., libs/grid/src/lib/features/row-numbers.ts)
import { RowNumberPlugin, type RowNumberConfig } from '../plugins/row-numbers';
import { registerFeature } from './registry';

// Augment the FeatureConfig interface so TypeScript knows about your feature
declare module '../core/types' {
  interface FeatureConfig {
    /** Enable row numbering. Shorthand: `true` or a start number. */
    rowNumbers?: boolean | number | RowNumberConfig;
  }
}

// Register the factory — convert shorthands to full plugin config
registerFeature('rowNumbers', (config) => {
  if (config === true) {
    return new RowNumberPlugin(); // defaults
  }
  if (typeof config === 'number') {
    return new RowNumberPlugin({ startFrom: config }); // shorthand
  }
  return new RowNumberPlugin(config as RowNumberConfig); // full config
});
```

### 2. The Pattern

Every feature module follows the same three steps:

1. **Import** the plugin class and its config type
2. **Augment** `FeatureConfig` via `declare module` — this adds your shorthand types to the `features` object
3. **Call** `registerFeature(name, factory)` — the factory receives the raw config value and returns a plugin instance

The factory function is responsible for converting shorthand values (`true`, `'row'`, a number, etc.) into the full plugin constructor config.

### 3. How It Works at Runtime

Feature modules are **side-effect imports** — importing the file automatically registers the feature:

```typescript
// Consumer code
import '@toolbox-web/grid/features/row-numbers'; // ← registers the feature

grid.gridConfig = {
  features: {
    rowNumbers: 5, // shorthand: start from 5
  },
};
```

If no one imports the feature module, it doesn't exist in the bundle — this is how tree-shaking works.

### 4. Common Shorthand Patterns

| Shorthand Type | Example | Usage |
|---------------|---------|-------|
| `boolean` | `filtering: true` | Enable with defaults |
| String literal | `selection: 'row'` | Pick a mode |
| `number` | `rowNumbers: 5` | Single numeric option |
| Full config | `editing: { editOn: 'click', ... }` | Full control |

### 5. Declaring Dependencies

If your feature depends on other features, declare it in the `PLUGIN_DEPENDENCIES` map in `registry.ts`:

```typescript
// In registry.ts
const PLUGIN_DEPENDENCIES: Record<string, string[]> = {
  clipboard: ['selection'],   // clipboard needs selection
  rowNumbers: [],             // no dependencies
};
```

The grid reorders plugins automatically based on declared dependencies and warns if a dependency is missing.

### 6. Framework Adapter Integration

For the feature to work with framework adapters (React, Vue, Angular), each adapter needs to re-export or reference the feature. The typical pattern:

```typescript
// libs/grid-react/src/features/row-numbers.ts
import '@toolbox-web/grid/features/row-numbers';
```

This ensures the side-effect import is available when consumers import from the adapter package:

```tsx
import '@toolbox-web/grid-react/features/row-numbers';

<DataGrid rows={rows} gridConfig={{ features: { rowNumbers: true } }} />
```

## See Also

  - [Plugins Overview](/grid/plugins.md): Built-in plugin catalog with dependencies and import paths
  - [Architecture](/grid/architecture.md): How plugins fit into the grid
  - [Events Reference](/grid/api-reference.md#events): Complete list of all grid and plugin events
  - [API Reference](/grid/api-reference.md): getPluginByName(), getPlugin(), and plugin access methods

---

# Framework Adapters

> How React, Angular, and Vue adapters let @toolbox-web/grid render framework-native components as cells, editors, and tool panels.

`@toolbox-web/grid` is a framework-agnostic web component, but most applications want their cell renderers, editors, and tool panels written in their host framework — JSX, Angular templates, Vue SFCs. **Framework adapters** are the bridge: each adapter intercepts grid rendering and mounts the appropriate framework primitive at the right DOM node.

Three official adapters ship today:

  - [Angular](/grid/angular/getting-started.md): @toolbox-web/grid-angular
  - [React](/grid/react/getting-started.md): @toolbox-web/grid-react
  - [Vue](/grid/vue/getting-started.md): @toolbox-web/grid-vue

You can also write your own adapter for any framework (Svelte, Solid, Lit, plain custom elements) — the contract is small and stable.

  - [Architecture](/grid/framework-adapters/architecture.md): How adapters integrate into the grid lifecycle, the FrameworkAdapter interface, registration, and invocation points.
  - [API Reference](/grid/api/framework-adapters/): Typed reference for FrameworkAdapter, registration helpers, and the cell-renderer / editor contracts.

---

# Framework Adapter Architecture

> How the @toolbox-web/grid framework-adapter system intercepts grid rendering to mount React, Angular, and Vue components in cells, editors, and tool panels.

Framework adapters let React, Angular, and Vue intercept grid rendering to support JSX components, Angular templates, and Vue slots as cell renderers and editors.

For an introduction and links to the official adapters, see [Framework Adapters](/grid/framework-adapters.md). For grid-core internals see [Architecture](/grid/architecture.md). For typed signatures see the [`FrameworkAdapter` API reference](/grid/api/framework-adapters/interfaces/frameworkadapter.md).

## Architecture

```mermaid
flowchart TB
    subgraph adapters["REGISTERED ADAPTERS"]
        A["ReactGridAdapter"]
        B["AngularGridAdapter"]
        C["VueGridAdapter"]
    end

    D["DataGridElement.registerAdapter()"]
    A --> D
    B --> D
    C --> D
    D --> E["Static adapter array<br/><i>(shared across all grids)</i>"]

    subgraph rendering["RENDERING PIPELINE"]
        F["Parse &lt;tbw-grid-column&gt;"]
        G["Cell render cycle"]
        H["Cell cleanup"]
    end

    E --> F
    E --> G
    E --> H
```

## FrameworkAdapter Interface

Adapters implement these methods:

| Method | Required | Purpose |
|--------|----------|---------|
| `canHandle(element)` | Yes | Check if this adapter can process the element |
| `createRenderer(element)` | Yes | Return a cell renderer function, or `undefined` to pass |
| `createEditor(element)` | Yes | Return a cell editor function, or `undefined` to pass |
| `processConfig(config)` | No | Transform framework-specific config (e.g., component classes → render functions) |
| `getTypeDefault(type)` | No | Provide app-wide type defaults from framework's DI/registry |
| `releaseCell(cellEl)` | No | Cleanup when cell DOM is recycled (unmount React roots, destroy Angular views) |
| `createToolPanelRenderer(element)` | No | Support framework components in tool panel sidebar |

## Registration

Adapters register statically on `DataGridElement` — typically at module load time:

```typescript
// React: registers immediately on import
const globalAdapter = new GridAdapter();
DataGridElement.registerAdapter(globalAdapter);

// Angular: registers via Grid directive
DataGridElement.registerAdapter(this.adapter);

// Vue: registers in DataGrid component onMounted()
```

This is why importing `@toolbox-web/grid-react` (or any adapter package) auto-registers the adapter — no separate setup needed.

## Adapter Invocation Points

Adapters are called at four points in the grid lifecycle:

**1. Light DOM Column Parsing** — When `<tbw-grid-column>` elements are parsed, each adapter is tried until one handles the renderer/editor:

```typescript
const viewAdapter = adapters.find((a) => a.canHandle(viewTarget));
if (viewAdapter) {
  config.viewRenderer = viewAdapter.createRenderer(viewTarget);
}
```

**2. Config Processing** — When `gridConfig` is set, the adapter can transform component classes to render functions:

```typescript
set gridConfig(value) {
  if (value && this.__frameworkAdapter?.processConfig) {
    value = this.__frameworkAdapter.processConfig(value);
  }
}
```

**3. Cell Rendering** — Type defaults are resolved through the adapter:

```typescript
const appDefault = adapter.getTypeDefault(col.type);
if (appDefault?.renderer) return appDefault.renderer;
```

**4. Cell Cleanup** — When virtualization recycles a row, adapters unmount framework components:

```typescript
grid.__frameworkAdapter?.releaseCell?.(cell);
// React: unmounts React root
// Angular: destroys component view
// Vue: unmounts app instance
```

## See Also

- **[Angular Adapter](/grid/angular/getting-started.md)** — `@toolbox-web/grid-angular` usage and base classes.
- **[React Adapter](/grid/react/getting-started.md)** — `@toolbox-web/grid-react` usage and patterns.
- **[Vue Adapter](/grid/vue/getting-started.md)** — `@toolbox-web/grid-vue` usage and composables.
- **[Plugin Architecture](/grid/plugin-development/architecture.md)** — How plugins integrate with the same render pipeline adapters hook into.

---

# Base Classes for Editors & Filter Panels

> BaseGridEditor, BaseGridEditorCVA, BaseOverlayEditor, and BaseFilterPanel — reusable base classes for custom Angular editors and filter panels.

The `@toolbox-web/grid-angular` package provides base classes that eliminate boilerplate when building custom editors and filter panels. Each class handles common infrastructure — lifecycle, cleanup, positioning, form integration — so you can focus on your component's UI and logic.

## Class Hierarchy

```
BaseGridEditor          ← common inputs/outputs, validation helpers
  ├── BaseGridEditorCVA  ← + ControlValueAccessor (dual grid/form use)
  └── BaseOverlayEditor  ← + floating overlay panel infrastructure
```

| Class | Purpose | Extend when… |
|-------|---------|--------------|
| `BaseGridEditor` | Inline cell editors | You need a simple input that renders inside the cell |
| `BaseGridEditorCVA` | Dual grid + form editors | The same component is used inside `<tbw-grid>` **and** standalone `<form>` |
| `BaseOverlayEditor` | Overlay/popup editors | You need a floating panel (date picker, autocomplete, dropdown) |
| `BaseFilterPanel` | Column filter panels | You need a custom filter UI for the FilteringPlugin |

---

## BaseGridEditor

The foundation class for all Angular cell editors. Provides common inputs, outputs, validation state, and automatic cleanup.

> **Full API:** [`BaseGridEditor`](/grid/angular/api/utilities/basegrideditor.md)

### API

| Member | Type | Description |
|--------|------|-------------|
| `value` | `input<TValue>()` | Cell value (fallback when no `FormControl`) |
| `row` | `input<TRow>()` | Row data object |
| `column` | `input<`[`ColumnConfig`](/grid/api/core/interfaces/columnconfig.md)`>()` | Column configuration |
| `control` | `input<AbstractControl>()` | Cell's `FormControl` (when using `FormArray`) |
| `commit` | `output<TValue \| null>()` | Emitted when value is committed (`null` clears the field) |
| `cancel` | `output<void>()` | Emitted when edit is cancelled |
| `currentValue()` | `Signal<TValue \| undefined>` | Resolved value (prefers `control.value` over `value`) |
| `isInvalid()` | `Signal<boolean>` | Mirrors `control.invalid` — `false` if no `control` is bound |
| `isDirty()` | `Signal<boolean>` | Mirrors `control.dirty` — `false` if no `control` is bound |
| `isTouched()` | `Signal<boolean>` | Mirrors `control.touched` — `false` if no `control` is bound |
| `hasErrors()` | `Signal<boolean>` | True when `control.errors` has any keys — `false` if no `control` is bound |
| `firstErrorMessage()` | `Signal<string>` | First validation error from `control.errors`, run through `getErrorMessage()` |
| `allErrorMessages()` | `Signal<string[]>` | Every validation error from `control.errors`, each run through `getErrorMessage()` |
| `commitValue(v)` | Method | Emit `commit` event + DOM `CustomEvent` (accepts `TValue \| null`) |
| `cancelEdit()` | Method | Emit `cancel` event + DOM `CustomEvent` |
| `isCellFocused()` | Method | Whether the parent cell has the `cell-focus` class |
| `getErrorMessage(key, value?)` | Method (override) | Customise validation error messages |
| `onBeforeEditClose()` | Hook (override) | Called before grid clears editing state — last chance to flush pending values |
| `onEditClose()` | Hook (override) | Called after the editing session ends — cleanup overlays/dropdowns |
| `onExternalValueChange(v)` | Hook (override) | Called when the cell value changes externally (cascade, undo/redo) |

### Example

```typescript
import { Component } from '@angular/core';
import { BaseGridEditor } from '@toolbox-web/grid-angular/features/editing';

@Component({
  selector: 'app-text-editor',
  template: `
    <input
      [value]="currentValue()"
      [class.is-invalid]="isInvalid()"
      (input)="commitValue($event.target.value)"
      (keydown.escape)="cancelEdit()"
    />
    @if (hasErrors()) {
      <div class="error">{{ firstErrorMessage() }}</div>
    }
  `
})
export class TextEditorComponent extends BaseGridEditor<MyRow, string> {
  protected override getErrorMessage(errorKey: string): string {
    if (errorKey === 'required') return 'This field is required';
    return super.getErrorMessage(errorKey);
  }
}
```

### Validation State & Reactivity

The validation signals — `isInvalid`, `isDirty`, `isTouched`, `hasErrors`,
`firstErrorMessage`, `allErrorMessages` — are **derived from the `control` input**.
They only carry meaning when the grid is bound to a `FormArray` and an
`AbstractControl` has been passed in via `[control]="control"`. Without a control,
they default to `false` / `''` / `[]`.

Because they are Angular `computed()` signals:

- They **don't run on a schedule** — they re-evaluate lazily, only when read.
- They re-fire automatically whenever `control.errors`, `control.invalid`,
  `control.dirty`, or `control.touched` changes — which Angular triggers on every
  value update, blur, or programmatic call to `markAsTouched()` /
  `updateValueAndValidity()`.
- If your template never reads them, they never compute.

**Error pipeline** — `firstErrorMessage()` and `allErrorMessages()` walk the
`control.errors` map and pipe each `(key, value)` pair through your
`getErrorMessage()` override. The first-vs-all distinction:

- **`firstErrorMessage()`** — the most common case; show one inline message
  (`{{ firstErrorMessage() }}` under the input).
- **`allErrorMessages()`** — when a single field can have several simultaneous
  errors you want to surface together (password complexity, multi-rule
  validators) rendered as a list.

---

## BaseGridEditorCVA

Combines `BaseGridEditor` with Angular's `ControlValueAccessor` interface. Use this when a single component needs to work both as a grid cell editor **and** as a standalone form control.

> **Full API:** [`BaseGridEditorCVA`](/grid/angular/api/utilities/basegrideditorcva.md)

### Additional API (on top of BaseGridEditor)

| Member | Type | Description |
|--------|------|-------------|
| `cvaValue` | `Signal<TValue \| null>` | Value written by the form control |
| `disabledState` | `Signal<boolean>` | Tracks `setDisabledState()` calls |
| `displayValue` | `Computed<TValue \| null>` | Prefers grid value, falls back to CVA value |
| `commitBoth(v)` | Method | Commits via both CVA `onChange` **and** grid `commitValue` |
| `writeValue` / `registerOn*` / `setDisabledState` | CVA methods | Full `ControlValueAccessor` implementation |

### Example

```typescript
import { Component, forwardRef } from '@angular/core';
import { NG_VALUE_ACCESSOR } from '@angular/forms';
import { BaseGridEditorCVA } from '@toolbox-web/grid-angular/features/editing';

@Component({
  selector: 'app-date-picker',
  providers: [{
    provide: NG_VALUE_ACCESSOR,
    useExisting: forwardRef(() => DatePickerComponent),
    multi: true,
  }],
  template: `
    <input
      type="date"
      [value]="displayValue()"
      [disabled]="disabledState()"
      (change)="commitBoth($event.target.value)"
      (keydown.escape)="cancelEdit()"
    />
  `
})
export class DatePickerComponent extends BaseGridEditorCVA<MyRow, string> {}
```

:::note
Subclasses must still provide `NG_VALUE_ACCESSOR` themselves because
`forwardRef(() => ConcreteClass)` must reference the concrete component — this
is an Angular limitation.
:::

### Using in both contexts

```typescript
// Inside a grid
<tbw-grid-column field="startDate" editable>
  <app-date-picker *tbwEditor="let value" [value]="value" />
</tbw-grid-column>

// Inside a standalone form
<app-date-picker formControlName="startDate" />
```

---

## BaseOverlayEditor

Base class for editors that display a **floating overlay panel** (date pickers, autocomplete dropdowns, color pickers, etc.). Handles all the positioning, focus gating, click-outside detection, and cleanup infrastructure.

> **Full API:** [`BaseOverlayEditor`](/grid/angular/api/utilities/baseoverlayeditor.md) · [`OverlayPosition`](/grid/angular/api/types/overlayposition.md)

### Features

- **CSS Anchor Positioning** with JS `getBoundingClientRect()` fallback for Firefox/Safari
- **Focus gating** — in row editing mode, only the focused cell's overlay is shown
- **Click-outside detection** — configurable via `onOverlayOutsideClick()`
- **Keyboard routing** — Enter/Space/ArrowDown/F2 open, Escape closes
- **Automatic teardown** — panel removed from `<body>` + all listeners cleaned up on destroy

### API

| Member | Type | Description |
|--------|------|-------------|
| `overlayPosition` | `OverlayPosition` | Position relative to cell: `'below'` (default), `'above'`, `'below-right'`, `'over-top-left'`, `'over-bottom-left'` |
| `initOverlay(panel)` | Method | Initialize with the panel element. Call in an `effect()` or `afterNextRender()`. |
| `showOverlay()` | Method | Show the overlay panel |
| `hideOverlay(suppressTab?)` | Method | Hide the overlay panel |
| `reopenOverlay()` | Method | Close and re-open (repositions after content change) |
| `teardownOverlay()` | Method | Remove panel from DOM + cleanup (auto-called on destroy) |
| `onInlineKeydown(e)` | Method | Keydown handler for the inline input |
| `onInlineClick()` | Method | Click handler for the inline input (toggle overlay) |
| `handleEscape(e)` | Method | Close overlay or cancel edit |
| `advanceGridFocus(backward?)` | Method | Dispatch synthetic Tab to move to next cell |
| `getInlineInput()` | **Abstract** | Return the inline `<input>` element (for focus return) |
| `onOverlayOutsideClick()` | **Abstract** | Called on click outside — typically call `hideOverlay()` |
| `onOverlayOpened()` | Hook | Called after overlay opens (focus inner element, etc.) |

### Example

```typescript
import { Component, viewChild, ElementRef, effect } from '@angular/core';
import { BaseOverlayEditor } from '@toolbox-web/grid-angular/features/editing';

@Component({
  selector: 'app-date-editor',
  template: `
    <input
      #inlineInput
      readonly
      [value]="currentValue()"
      (click)="onInlineClick()"
      (keydown)="onInlineKeydown($event)"
    />
    <div #panel class="tbw-overlay-panel" style="width: 280px; padding: 12px;">
      <input
        type="date"
        [value]="currentValue()"
        (change)="selectAndClose($event.target.value)"
      />
      <div class="actions">
        <button (click)="hideOverlay()">Cancel</button>
      </div>
    </div>
  `
})
export class DateEditorComponent extends BaseOverlayEditor<MyRow, string> {
  panelRef = viewChild.required<ElementRef<HTMLElement>>('panel');
  inputRef = viewChild.required<ElementRef<HTMLInputElement>>('inlineInput');

  protected override overlayPosition = 'below' as const;

  constructor() {
    super();
    effect(() => {
      const panel = this.panelRef().nativeElement;
      this.initOverlay(panel);
      if (this.isCellFocused()) this.showOverlay();
    });
  }

  protected getInlineInput(): HTMLInputElement | null {
    return this.inputRef()?.nativeElement ?? null;
  }

  protected onOverlayOutsideClick(): void {
    this.hideOverlay();
  }

  selectAndClose(date: string): void {
    this.commitValue(date);
    this.hideOverlay();
  }
}
```

### Overlay Position Options

| Value | Description |
|-------|-------------|
| `'below'` | Panel below the cell, left-aligned (default). Flips above if viewport overflows. |
| `'above'` | Panel above the cell, left-aligned. Flips below if off-screen. |
| `'below-right'` | Panel below the cell, right-aligned. Flips above if viewport overflows. |
| `'over-top-left'` | Panel top-left aligns with cell top-left (opens downward). No flip. |
| `'over-bottom-left'` | Panel bottom-left aligns with cell bottom-left (opens upward). No flip. |

### CSS Customization

The overlay panel uses CSS custom properties from the grid theme:

| Variable | Default | Description |
|----------|---------|-------------|
| `--tbw-overlay-bg` | `#fff` | Panel background |
| `--tbw-overlay-border` | `#ccc` | Panel border color |
| `--tbw-overlay-radius` | `4px` | Panel border radius |
| `--tbw-overlay-shadow` | `0 4px 12px rgba(0,0,0,0.15)` | Panel box shadow |

---

## BaseFilterPanel

Base class for custom column filter panels used with the `FilteringPlugin`. Provides the `params` input and lifecycle helpers so you only need to implement your filter logic.

> **Full API:** [`BaseFilterPanel`](/grid/angular/api/utilities/basefilterpanel.md) · [`FilterPanelParams`](/grid/plugins/filtering/interfaces/filterpanelparams.md)

### API

| Member | Type | Description |
|--------|------|-------------|
| `params` | `input.required<FilterPanelParams>()` | Injected by the grid's filtering infrastructure |
| `applyFilter()` | **Abstract** | Implement your filter logic here |
| `applyAndClose()` | Method | Calls `applyFilter()` then `closePanel()` |
| `clearAndClose()` | Method | Calls `clearFilter()` then `closePanel()` |

### FilterPanelParams

The `params` input provides these members (see [`FilterPanelParams`](/grid/plugins/filtering/interfaces/filterpanelparams.md) for the full type):

| Property | Type | Description |
|----------|------|-------------|
| `field` | `string` | Column field name |
| `column` | [`ColumnConfig`](/grid/api/core/interfaces/columnconfig.md) | Full column configuration |
| `uniqueValues` | `unknown[]` | Distinct values in the column |
| `excludedValues` | `Set<unknown>` | Currently excluded values (set filter) |
| `searchText` | `string` | Current search text |
| `currentFilter?` | `FilterModel` | Currently active filter for this column, if any |
| `applySetFilter(excludedValues, valueTo?)` | Method | Apply include/exclude filter (pass an **array** of excluded values) |
| `applyTextFilter(operator, value, valueTo?)` | Method | Apply text/number filter |
| `clearFilter()` | Method | Clear column filter |
| `closePanel()` | Method | Close filter panel |

### Example: Text Filter

```typescript
import { Component, viewChild, ElementRef, afterNextRender } from '@angular/core';
import { BaseFilterPanel } from '@toolbox-web/grid-angular/features/filtering';

@Component({
  selector: 'app-text-filter',
  template: `
    <div class="filter-panel">
      <input
        #input
        placeholder="Search..."
        (keydown.enter)="applyAndClose()"
      />
      <div class="actions">
        <button (click)="applyAndClose()">Apply</button>
        <button (click)="clearAndClose()">Clear</button>
      </div>
    </div>
  `
})
export class TextFilterComponent extends BaseFilterPanel {
  input = viewChild.required<ElementRef<HTMLInputElement>>('input');

  constructor() {
    super();
    afterNextRender(() => {
      this.input().nativeElement.focus();
    });
  }

  applyFilter(): void {
    this.params().applyTextFilter('contains', this.input().nativeElement.value);
  }
}
```

### Example: Set Filter (Checkbox List)

```typescript
import { Component, signal } from '@angular/core';
import { BaseFilterPanel } from '@toolbox-web/grid-angular/features/filtering';

@Component({
  selector: 'app-set-filter',
  template: `
    <div class="filter-panel">
      @for (val of params().uniqueValues; track val) {
        <label>
          <input
            type="checkbox"
            [checked]="!excluded().has(val)"
            (change)="toggle(val)"
          />
          {{ val }}
        </label>
      }
      <div class="actions">
        <button (click)="applyAndClose()">Apply</button>
        <button (click)="clearAndClose()">Clear</button>
      </div>
    </div>
  `
})
export class SetFilterComponent extends BaseFilterPanel {
  excluded = signal(new Set<unknown>());

  toggle(value: unknown): void {
    this.excluded.update(set => {
      const next = new Set(set);
      next.has(value) ? next.delete(value) : next.add(value);
      return next;
    });
  }

  applyFilter(): void {
    // applySetFilter takes an array, not a Set
    this.params().applySetFilter([...this.excluded()]);
  }
}
```

### Usage in Column Config

```typescript
import type { GridConfig } from '@toolbox-web/grid-angular';
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import { TextFilterComponent } from './text-filter.component';
import { SetFilterComponent } from './set-filter.component';

const gridConfig: GridConfig = {
  columns: [
    { field: 'name', filterable: true, filterPanel: TextFilterComponent },
    { field: 'status', filterable: true, filterPanel: SetFilterComponent },
  ],
  features: { filtering: true },
};
```

---

## When to Use Which Class

| Scenario | Base Class |
|----------|-----------|
| Simple text/number input in cell | `BaseGridEditor` |
| Date picker input used in both grid and forms | `BaseGridEditorCVA` |
| Dropdown/autocomplete with floating panel | `BaseOverlayEditor` |
| Custom column filter UI | `BaseFilterPanel` |
| Date picker overlay + form control | Compose: extend `BaseOverlayEditor` and implement `ControlValueAccessor` manually |

## Imports

All base classes are exported from the main package:

```typescript
import { BaseGridEditor, BaseGridEditorCVA, BaseOverlayEditor, type OverlayPosition } from '@toolbox-web/grid-angular/features/editing';
import { BaseFilterPanel } from '@toolbox-web/grid-angular/features/filtering';

```

---

# Angular Integration

> Install and configure @toolbox-web/grid-angular — feature inputs, renderers, editors, events, inject functions, and Angular-specific patterns.

The `@toolbox-web/grid-angular` package provides Angular integration for the `<tbw-grid>` data grid component.

:::note[Where to find feature docs]
This page covers Angular-specific setup and APIs (feature inputs, inject functions, Angular directives). Core grid features and plugins — cell renderers, editors, events, master-detail, sorting, filtering, selection, etc. — are documented on the [Core](/grid/core.md) and [Plugins](/grid/plugins.md) pages, each with an Angular tab and runnable demos.
:::

## Compatibility

| Angular version | Support level |
| --------------- | ------------- |
| 21              | **Tested** — used in demos and CI |
| 20              | **Tested** |
| 17 – 19         | Supported (minimum peer dependency) |
| &lt; 17         | Not supported — adapter uses `input()` / `output()` signal APIs |

## Installation

#### npm

  ```bash
  npm install @toolbox-web/grid @toolbox-web/grid-angular
  ```

#### yarn

  ```bash
  yarn add @toolbox-web/grid @toolbox-web/grid-angular
  ```

#### pnpm

  ```bash
  pnpm add @toolbox-web/grid @toolbox-web/grid-angular
  ```

#### bun

  ```bash
  bun add @toolbox-web/grid @toolbox-web/grid-angular
  ```

## Setup

No bootstrap step is required. Importing `@toolbox-web/grid-angular` (or any of its `features/*` entries) registers the `<tbw-grid>` custom element as a side effect. Each feature is enabled per-component by importing its directive — see [Three Ways to Configure Features](#three-ways-to-configure-features) below.

```typescript
// Optional: if you also want to use <tbw-grid> in plain HTML templates
// outside an Angular component (rare), add this once in main.ts:
import '@toolbox-web/grid';
```

## Three Ways to Configure Features

You can enable plugins on `<tbw-grid>` with one of three patterns. Pick whichever fits the component — they can be mixed.

| Pattern | Best for | v2 status |
|---------|----------|-----------|
| **`gridConfig.features`** (object literal) | Configuration-driven apps; the entire grid setup lives in one object | ✅ Unchanged — fully supported |
| **Per-feature directive** (e.g. `GridFilteringDirective`) | Template-driven apps that want signal inputs/outputs **and** the smallest bundle | ✅ **Recommended** — the future-proof path |
| **Inputs/outputs on `Grid`** (e.g. `[filtering]`, `(filterChange)`) | v1.x apps already on this style | ⚠️ **Deprecated** — bindings remain in v1.x for compatibility but will be removed in v2.0 |

> **`gridConfig` users are not affected by the v2 cleanup** — only consumers binding feature inputs directly on `<tbw-grid>` need to switch to per-feature directives before v2.

### Recommended: Per-Feature Directives

Each feature ships its own attribute-selector directive (`GridFilteringDirective`, `GridSelectionDirective`, …) from its secondary entry. Add the directive to the component's `imports` and bind exactly the same `[input]` / `(output)` you used before:

```typescript
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';

@Component({
  imports: [Grid, GridFilteringDirective, GridSelectionDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [filtering]="true"
      (filterChange)="onFilter($event)"
      [selection]="'range'"
    />
  `,
})
export class MyGrid {/* … */}
```

**Why this is the preferred path:**

- **Tree-shakeable typed surface** — the feature's `input()` / `output()` definitions ship inside the feature's own bundle. Apps that don't import the directive don't pay for its compiled metadata in the core bundle.
- **Compile-time safety** — Angular errors with `Can't bind to 'filtering' since it isn't a known property of 'tbw-grid'` if you forget the directive (stronger than React/Vue, which silently drop unknown props).
- **Same bindings, same demos** — the directive's selector matches the existing attributes (`tbw-grid[filtering], tbw-grid[filterChange]`), so migrating from the deprecated style is a one-line `imports` addition per feature with **zero template changes**.

### Legacy: Inputs/Outputs on `Grid` (deprecated)

The v1.x style — declaring `[filtering]`, `(filterChange)`, etc. directly on the `Grid` directive without importing a per-feature directive — still works for the entire v1.x line but is `@deprecated` in JSDoc. v2.0 will remove these bindings from `Grid`, at which point a one-line directive import per feature is the migration.

## Basic Usage

The simplest way to use the grid is with the `Grid` directive and per-feature directives:

```typescript
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
import { GridEditingDirective } from '@toolbox-web/grid-angular/features/editing';
import { GridMultiSortDirective } from '@toolbox-web/grid-angular/features/multi-sort';
import { GridFilteringDirective } from '@toolbox-web/grid-angular/features/filtering';
import type { ColumnConfig } from '@toolbox-web/grid';

interface Employee {
  id: number;
  name: string;
  department: string;
  salary: number;
}

@Component({
  selector: 'app-employee-grid',
  imports: [Grid, GridSelectionDirective, GridEditingDirective, GridMultiSortDirective, GridFilteringDirective],
  template: `
    <tbw-grid
      [rows]="employees"
      [columns]="columns"
      [selection]="'range'"
      [editing]="'dblclick'"
      [multiSort]="true"
      [filtering]="{ debounceMs: 200 }"
      style="height: 400px; display: block;"
    />
  `,
})
export class EmployeeGridComponent {
  employees: Employee[] = [
    { id: 1, name: 'Alice', department: 'Engineering', salary: 95000 },
    { id: 2, name: 'Bob', department: 'Marketing', salary: 75000 },
    { id: 3, name: 'Charlie', department: 'Sales', salary: 85000 },
  ];

  columns: ColumnConfig<Employee>[] = [
    { field: 'id', header: 'ID', type: 'number', width: 70 },
    { field: 'name', header: 'Name', editable: true, sortable: true },
    { field: 'department', header: 'Department', editable: true, sortable: true },
    { field: 'salary', header: 'Salary', type: 'number', format: (v: number) => '$' + v.toLocaleString() },
  ];
}
```

## Feature Input Reference

Each feature exposes an input + (optional) output. The recommended way to use them is to import the matching **per-feature directive** alongside `Grid` (left column). The same `[input]` / `(output)` bindings are also accepted directly on `Grid` in v1.x for backward compatibility, but those bindings on `Grid` are `@deprecated` and will be removed in v2.0 — see the [Grid directive API](/grid/angular/api/directives/grid.md).

| Per-Feature Directive (recommended) | Input | Feature Import | Description |
|-------------------------------------|-------|----------------|-------------|
| [`GridSelectionDirective`](/grid/angular/api/directives/gridselectiondirective.md) | `[selection]` | `features/selection` | Cell, row, or range selection |
| [`GridEditingDirective`](/grid/angular/api/directives/grideditingdirective.md) | `[editing]` | `features/editing` | Inline cell editing |
| [`GridMultiSortDirective`](/grid/angular/api/directives/gridmultisortdirective.md) | `[multiSort]` | `features/multi-sort` | Multi-column sorting |
| [`GridFilteringDirective`](/grid/angular/api/directives/gridfilteringdirective.md) | `[filtering]` | `features/filtering` | Column filtering |
| [`GridClipboardDirective`](/grid/angular/api/directives/gridclipboarddirective.md) | `[clipboard]` | `features/clipboard` | Copy/paste support |
| [`GridContextMenuDirective`](/grid/angular/api/directives/gridcontextmenudirective.md) | `[contextMenu]` | `features/context-menu` | Right-click context menu |
| [`GridReorderColumnsDirective`](/grid/angular/api/directives/gridreordercolumnsdirective.md) | `[reorderColumns]` | `features/reorder-columns` | Column drag-to-reorder |
| [`GridVisibilityDirective`](/grid/angular/api/directives/gridvisibilitydirective.md) | `[visibility]` | `features/visibility` | Column visibility panel |
| [`GridPinnedColumnsDirective`](/grid/angular/api/directives/gridpinnedcolumnsdirective.md) | `[pinnedColumns]` | `features/pinned-columns` | Sticky left/right columns |
| [`GridPinnedRowsDirective`](/grid/angular/api/directives/gridpinnedrowsdirective.md) | `[pinnedRows]` | `features/pinned-rows` | Sticky top/bottom rows |
| [`GridGroupingColumnsDirective`](/grid/angular/api/directives/gridgroupingcolumnsdirective.md) | `[groupingColumns]` | `features/grouping-columns` | Multi-level column headers |
| [`GridGroupingRowsDirective`](/grid/angular/api/directives/gridgroupingrowsdirective.md) | `[groupingRows]` | `features/grouping-rows` | Row grouping |
| [`GridColumnVirtualizationDirective`](/grid/angular/api/directives/gridcolumnvirtualizationdirective.md) | `[columnVirtualization]` | `features/column-virtualization` | Virtualize columns for wide grids |
| [`GridRowDragDropDirective`](/grid/angular/api/directives/gridrowdragdropdirective.md) | `[rowDragDrop]` / `[reorderRows]` | `features/row-drag-drop` | Row drag-and-drop (within and across grids) |
| [`GridTreeDirective`](/grid/angular/api/directives/gridtreedirective.md) | `[tree]` | `features/tree` | Hierarchical tree view |
| [`GridMasterDetailDirective`](/grid/angular/api/directives/gridmasterdetaildirective.md) | `[masterDetail]` | `features/master-detail` | Expandable detail rows |
| [`GridResponsiveDirective`](/grid/angular/api/directives/gridresponsivedirective.md) | `[responsive]` | `features/responsive` | Card layout for narrow viewports |
| [`GridTooltipDirective`](/grid/angular/api/directives/gridtooltipdirective.md) | `[tooltip]` | `features/tooltip` | Cell / header tooltips |
| [`GridUndoRedoDirective`](/grid/angular/api/directives/gridundoredodirective.md) | `[undoRedo]` | `features/undo-redo` | Edit undo/redo |
| [`GridExportDirective`](/grid/angular/api/directives/gridexportdirective.md) | `[export]` | `features/export` | CSV/Excel export |
| [`GridPrintDirective`](/grid/angular/api/directives/gridprintdirective.md) | `[print]` | `features/print` | Print support |
| [`GridPivotDirective`](/grid/angular/api/directives/gridpivotdirective.md) | `[pivot]` | `features/pivot` | Pivot table functionality |
| [`GridServerSideDirective`](/grid/angular/api/directives/gridserversidedirective.md) | `[serverSide]` | `features/server-side` | Server-side data loading |
| [`GridStickyRowsDirective`](/grid/angular/api/directives/gridstickyrowsdirective.md) | `[stickyRows]` | `features/sticky-rows` | Pin selected data rows below the header on scroll |

**Core Config Inputs (no feature import needed):**

| Input | Type | Description |
|-------|------|-------------|
| `[rows]` | `T[]` | Row data — omit when using `[serverSide]` |
| `[columns]` | [`ColumnConfig`](/grid/api/core/interfaces/columnconfig.md)`[]` | Column definitions (alternative to `gridConfig.columns`) |
| `[gridConfig]` | [`GridConfig`](/grid/api/core/interfaces/gridconfig.md) | Full grid configuration object |
| `[loading]` | `boolean` | Show the grid's loading overlay |
| `[fitMode]` | `FitMode` | Column-fit strategy (`'auto'`, `'fill'`, `'fill-rest'`, etc.) |
| `[customStyles]` | `string` | CSS injected into the grid — useful for custom renderer/editor styling |
| `[sortable]` | `boolean` | Grid-wide sorting toggle (default: true) |
| `[filterable]` | `boolean` | Grid-wide filtering toggle (default: true). Requires FilteringPlugin. |
| `[selectable]` | `boolean` | Grid-wide selection toggle (default: true). Requires SelectionPlugin. |

## Programmatic Grid Access

Use [`injectGrid()`](/grid/angular/api/utilities/injectgrid.md) for programmatic access to the grid. It provides a reactive API via signals — see [`InjectGridReturn`](/grid/angular/api/types/injectgridreturn.md) for the full return shape:

```typescript
import { Component, effect } from '@angular/core';
import { Grid, injectGrid } from '@toolbox-web/grid-angular';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid],
  template: `
    <tbw-grid [rows]="employees" [columns]="columns"></tbw-grid>

    <p>Grid ready: {{ grid.isReady() }}</p>
    <button (click)="refresh()">Force Layout</button>
  `,
})
export class EmployeeGridComponent {
  grid = injectGrid();

  employees = [/* ... */];
  columns = [/* ... */];

  constructor() {
    effect(() => {
      if (this.grid.isReady()) {
        console.log('Grid element:', this.grid.element());
      }
    });
  }

  refresh() {
    this.grid.forceLayout();
  }
}
```

## Feature-Scoped Inject Functions

Feature imports export **scoped inject functions** for type-safe programmatic access to plugin functionality — no direct plugin references needed.

```typescript
import { GridExportDirective } from '@toolbox-web/grid-angular/features/export';
import { injectGridExport } from '@toolbox-web/grid-angular/features/export';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, GridExportDirective],
  template: `
    <div class="toolbar">
      <button (click)="exportCsv()" [disabled]="gridExport.isExporting()">Export CSV</button>
    </div>
    <tbw-grid [rows]="employees" [columns]="columns" [export]="true" />
  `,
})
export class ExportGridComponent {
  employees = [/* ... */];
  columns = [/* ... */];
  gridExport = injectGridExport();

  exportCsv() {
    this.gridExport.exportToCsv('employees.csv');
  }
}
```

### Available Inject Functions

See the **API Reference > Inject Functions** section for detailed method signatures, return types, and examples.

All inject functions accept an optional `selector` parameter (defaults to `'tbw-grid'`) to target a specific grid when a component contains multiple grids:

```typescript
// Target a specific grid by CSS selector
gridSelection = injectGridSelection('tbw-grid.primary');
gridExport = injectGridExport('#secondary-grid');
```

| Function | Import | Key Methods |
|----------|--------|-------------|
| [`injectGrid()`](/grid/angular/api/utilities/injectgrid.md) | `@toolbox-web/grid-angular` | `element`, `isReady`, `config`, `forceLayout`, `toggleGroup`, `registerStyles`, `visibleColumns` |
| [`injectGridSelection()`](/grid/angular/api/features/injectgridselection.md) | `features/selection` | `selectAll`, `clearSelection`, `getSelection`, `selectedRowIndices` (Signal) |
| [`injectGridFiltering()`](/grid/angular/api/features/injectgridfiltering.md) | `features/filtering` | `setFilter`, `clearAllFilters`, `getFilters`, `getFilteredRowCount` |
| [`injectGridExport()`](/grid/angular/api/features/injectgridexport.md) | `features/export` | `exportToCsv`, `exportToExcel`, `exportToJson`, `isExporting` |
| [`injectGridPrint()`](/grid/angular/api/features/injectgridprint.md) | `features/print` | `print`, `isPrinting` |
| [`injectGridUndoRedo()`](/grid/angular/api/features/injectgridundoredo.md) | `features/undo-redo` | `undo`, `redo`, `canUndo` (Signal), `canRedo` (Signal) |

### Signal-Based Selection Example

```typescript
import { Component, computed } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import { injectGridSelection } from '@toolbox-web/grid-angular/features/selection';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid],
  template: `
    <tbw-grid [rows]="employees" [gridConfig]="gridConfig"></tbw-grid>
    <p>Selected: {{ selectedCount() }}</p>
    <button (click)="gridSelection.selectAll()">Select All</button>
    <button (click)="gridSelection.clearSelection()">Clear</button>
  `,
})
export class EmployeeGridComponent {
  gridSelection = injectGridSelection();
  selectedCount = computed(() => this.gridSelection.selectedRowIndices().length);

  gridConfig = {
    features: { selection: { mode: 'row', checkbox: true } },
  };
}
```

## Type-Level Defaults

Register application-wide renderers and editors for specific data types using [`provideGridTypeDefaults()`](/grid/angular/api/utilities/providegridtypedefaults.md):

```typescript
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideGridTypeDefaults } from '@toolbox-web/grid-angular';
import { CurrencyRendererComponent, DateRendererComponent } from './renderers';

export const appConfig: ApplicationConfig = {
  providers: [
    provideGridTypeDefaults({
      currency: { renderer: CurrencyRendererComponent },
      date: { renderer: DateRendererComponent },
    }),
  ],
};
```

For dynamic registration at runtime, inject [`GridTypeRegistry`](/grid/angular/api/utilities/gridtyperegistry.md):

```typescript
import { inject } from '@angular/core';
import { GridTypeRegistry } from '@toolbox-web/grid-angular';

export class AppComponent {
  private registry = inject(GridTypeRegistry);

  ngOnInit() {
    this.registry.register('currency', {
      renderer: CurrencyCellComponent,
    });
  }
}
```

## Custom Icons

The grid supports two complementary ways to customize icons — see the [Theming Guide → Icon Customization](/grid/guides/theming.md#icon-customization) for both the CSS and JavaScript approaches:

- **CSS variables** (`--tbw-icon-*`) — preferred for themes and static customization; no JavaScript needed.
- **`gridConfig.icons`** — for dynamic icons, icon libraries, or `HTMLElement` instances; takes precedence over CSS.

[`provideGridIcons()`](/grid/angular/api/utilities/providegridicons.md) is the Angular DI wrapper for the JS path — it injects `icons` into `gridConfig.icons` for every grid in the application:

```typescript
// app.config.ts
import { provideGridIcons } from '@toolbox-web/grid-angular';

export const appConfig = {
  providers: [
    provideGridIcons({
      sortAsc: '<svg>...</svg>',
      sortDesc: '<svg>...</svg>',
      filter: '<svg>...</svg>',
    }),
  ],
};
```

## Manual Plugin Instantiation

While feature inputs are recommended, you can instantiate plugins manually for custom configurations or third-party plugins:

```typescript
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import { SelectionPlugin, EditingPlugin, ClipboardPlugin } from '@toolbox-web/grid/all';
import type { GridConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid],
  template: `<tbw-grid [rows]="employees" [gridConfig]="gridConfig"></tbw-grid>`,
})
export class EmployeeGridComponent {
  employees = [/* ... */];

  gridConfig: GridConfig = {
    columns: [
      { field: 'id', header: 'ID' },
      { field: 'name', header: 'Name', editable: true },
    ],
    plugins: [
      new SelectionPlugin({ mode: 'range', checkbox: true }),
      new EditingPlugin({ editOn: 'dblclick' }),
      new ClipboardPlugin({ includeHeaders: true }),
    ],
  };
}
```

Feature inputs and manual plugins can be mixed — the grid merges them, with manual plugins added first.

## Angular-Specific Directives

### Custom Tool Panels

Use the [`GridToolPanel`](/grid/angular/api/directives/gridtoolpanel.md) directive to declare a custom sidebar panel inline. Place a `<tbw-grid-tool-panel>` element inside the grid with an `<ng-template>` for its content — the template receives the grid element as its implicit context (and as `let-grid`):

```typescript
import { Component } from '@angular/core';
import { Grid, GridToolPanel } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, GridToolPanel],
  template: `
    <tbw-grid [rows]="employees" [columns]="columns">
      <tbw-grid-tool-panel
        id="stats"
        title="Statistics"
        icon="📊"
        [order]="10"
      >
        <ng-template let-grid>
          <div class="stats-panel">
            <h3>Statistics</h3>
            <p>Total rows: {{ employees.length }}</p>
          </div>
        </ng-template>
      </tbw-grid-tool-panel>
    </tbw-grid>
  `,
})
export class EmployeeGridComponent {
  employees = [/* ... */];
  columns = [/* ... */];
}
```

**Inputs:** `id` (required), `title` (required), `icon`, `tooltip`, `order` (default `100`, lower = first).

### Header & Toolbar Content

Inject Angular components into the grid's shell header (left zone) or toolbar (right zone) via the [`GridHeaderContent`](/grid/angular/api/directives/gridheadercontent.md) and [`GridToolbarContent`](/grid/angular/api/directives/gridtoolbarcontent.md) directives. These wrap the imperative `registerHeaderContent` / `registerToolbarContent` APIs and mount an `<ng-template>` so projected components retain full DI, change detection, and signal reactivity.

```typescript
import { Component, signal } from '@angular/core';
import { Grid, GridHeaderContent, GridToolbarContent } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, GridHeaderContent, GridToolbarContent, HeaderNavComponent, ToolbarNavComponent],
  template: `
    <tbw-grid [rows]="rows()" [gridConfig]="config()">
      <tbw-grid-header-content id="calendar-nav" [order]="0">
        <ng-template>
          <app-header-nav [year]="year()" (yearChange)="onYearChange($event)" />
        </ng-template>
      </tbw-grid-header-content>
      <tbw-grid-toolbar-content id="calendar-buttons" [order]="0">
        <ng-template>
          <app-toolbar-nav (previous)="prev()" (today)="today()" (next)="next()" />
        </ng-template>
      </tbw-grid-toolbar-content>
    </tbw-grid>
  `,
})
export class CalendarGridComponent {
  year = signal(new Date().getFullYear());
  onYearChange(year: number) { this.year.set(year); }
}
```

**Inputs:** `id` (optional — auto-generated if omitted), `order` (default `100`, lower = first). Template bindings re-evaluate via Angular change detection without re-registering with the grid.

## Server-Side Data Loading

The full data-source contract, sort/filter modes, prefetching, cancellation and live-update patterns are documented on the [Server-Side plugin](/grid/plugins/server-side.md) page (it has runnable demos and an Angular tab in every example). The two Angular-specific points worth calling out here:

1. **Use the per-feature directive (recommended).** Add [`GridServerSideDirective`](/grid/angular/api/directives/gridserversidedirective.md) to your component's `imports` if you want to bind via `[serverSide]="…"` on `<tbw-grid>`. If you configure server-side through `[gridConfig]="{ features: { serverSide: … } }"` instead, no extra directive is needed — the deprecated `[serverSide]` binding on `Grid` itself still works in v1.x but will be removed in v2.0.
2. **Return the `HttpClient` `Observable` directly from `getRows`.** No `firstValueFrom`, no manual `takeUntil`. The grid subscribes once and calls `unsubscribe()` when the request is superseded (sort change, fast scrolling, `refresh()`); `HttpClient` cancels the underlying XHR in response, which is the only correct way to avoid stale-buffer races.

```typescript
import { Component, inject } from '@angular/core';
import { HttpClient, HttpParams } from '@angular/common/http';
import { map } from 'rxjs/operators';
import { Grid } from '@toolbox-web/grid-angular';
import { GridServerSideDirective } from '@toolbox-web/grid-angular/features/server-side';
import type { GridConfig } from '@toolbox-web/grid';
import type { ServerSideDataSource } from '@toolbox-web/grid/plugins/server-side';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid, GridServerSideDirective],
  template: `<tbw-grid [gridConfig]="gridConfig" style="height: 400px; display: block;"></tbw-grid>`,
})
export class EmployeeGridComponent {
  private http = inject(HttpClient);

  private dataSource: ServerSideDataSource<Employee> = {
    getRows: (params) => {
      const httpParams = new HttpParams()
        .set('offset', params.startNode)
        .set('limit', params.endNode - params.startNode);
      return this.http
        .get<{ items: Employee[]; total: number }>('/api/employees', { params: httpParams })
        .pipe(map((data) => ({ rows: data.items, totalNodeCount: data.total })));
    },
  };

  gridConfig: GridConfig<Employee> = {
    columns: [/* … */],
    features: { serverSide: { dataSource: this.dataSource } },
  };
}
```

> **Caching:** Angular has no built-in equivalent to TanStack Query's request cache. If you need cross-component caching, deduplication or `staleTime`, wrap the `HttpClient` call in your own service (e.g. with `shareReplay`), or evaluate [`@tanstack/angular-query-experimental`](https://tanstack.com/query/latest/docs/framework/angular/overview) — note the `experimental` tag.

## Dynamic Row Updates

```typescript
import { Component, signal } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid],
  template: `
    <tbw-grid [rows]="employees()" [columns]="columns"></tbw-grid>
    <button (click)="addEmployee()">Add</button>
    <button (click)="removeFirst()">Remove First</button>
  `,
})
export class EmployeeGridComponent {
  employees = signal([
    { id: 1, name: 'Alice', department: 'Engineering' },
    { id: 2, name: 'Bob', department: 'Design' },
  ]);

  columns = [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'department', header: 'Department' },
  ];

  private nextId = 3;

  addEmployee() {
    this.employees.update(rows => [
      ...rows,
      { id: this.nextId++, name: 'New Employee', department: 'TBD' },
    ]);
  }

  removeFirst() {
    this.employees.update(rows => rows.slice(1));
  }
}
```

> **Tip**: Use Angular signals for rows. The grid detects the new array reference and re-renders efficiently.

## Performance Tips

### OnPush Change Detection

```typescript
@Component({
  changeDetection: ChangeDetectionStrategy.OnPush,
  // ...
})
export class EmployeeGridComponent { }
```

### Define Columns Once

```typescript
// ✅ Good — assigned once
readonly columns: ColumnConfig[] = [
  { field: 'id', header: 'ID' },
  { field: 'name', header: 'Name' },
];

// ❌ Bad — getter creates new array every check
get columns() {
  return [{ field: 'id', header: 'ID' }, { field: 'name', header: 'Name' }];
}
```

## Troubleshooting

### Feature input not working

Ensure you imported the feature side-effect in your `main.ts`:

```typescript
// main.ts — must be imported before bootstrap
import { GridSelectionDirective } from '@toolbox-web/grid-angular/features/selection';
```

### "is not a known element" errors

The `@toolbox-web/grid-angular` adapter provides directives that register all `<tbw-*>` elements with Angular's template compiler — no `CUSTOM_ELEMENTS_SCHEMA` needed. Import the directive that matches the element used in your template:

```typescript
import { Grid, TbwGridColumn } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, TbwGridColumn], // Grid → <tbw-grid>, TbwGridColumn → <tbw-grid-column>
  // ...
})
```

### Grid not rendering

The grid needs a defined height for virtualization. See [Troubleshooting → Height & Virtualization](/grid/guides/troubleshooting.md#height--virtualization) for solutions.

### Row updates not reflected

The grid detects updates via reference equality. Always assign a new array:

```typescript
// ✅ New reference — grid re-renders
this.employees.update(rows => [...rows, newRow]);

// ❌ Same reference — grid won't detect change
this.employees().push(newRow);
```

## See Also

- **[Base Classes](/grid/angular/base-classes.md)** — `BaseOverlayEditor`, `BaseGridEditorCVA`, `BaseFilterPanel`
- **[Reactive Forms](/grid/angular/reactive-forms.md)** — `FormArray` integration with `GridFormArray` and `GridLazyForm`
- **API Reference** — Browse all directives, utilities, and types via the Angular API section in the sidebar
- **[Grid Plugins](/grid/plugins.md)** — All available plugins
- **[Core Features](/grid/core.md)** — Variable row heights, events, column config

---

# Reactive Forms Integration

> Bind @toolbox-web/grid to Angular FormArray — cell-level validation, dirty tracking, lazy form binding, and automatic validation styling.

The `@toolbox-web/grid-angular` package provides seamless integration with Angular Reactive Forms, allowing the grid to act as a form-bound component with cell-level validation.

> **Pair with the editing directive.** [`GridFormArray`](/grid/angular/api/utilities/gridformarray.md) and [`GridLazyForm`](/grid/angular/api/utilities/gridlazyform.md) are themselves form-binding directives — they do **not** turn editing on. To allow cell edits, also add [`GridEditingDirective`](/grid/angular/api/directives/grideditingdirective.md) (from `@toolbox-web/grid-angular/features/editing`) to the component's `imports`, **or** configure editing through `[gridConfig]="{ features: { editing: … } }"`. The legacy `[editing]` binding on `Grid` itself is `@deprecated` and will be removed in v2.0.

## Overview

You can bind a grid to a `FormArray` using the `[formArray]` directive. This enables:

- **Two-way data binding** - FormArray value changes update the grid, and cell edits update the FormArray
- **Validation state** - Access cell-level and row-level validation
- **Dirty/touched tracking** - Know when users have interacted with the grid
- **FormControl in editors** - Custom editors can bind directly to cell-level FormControls

## Usage with FormArray

Use a `FormArray` of `FormGroup`s for full validation support. This exposes cell-level `FormControl`s in the editor context.

> **Directive:** [`GridFormArray`](/grid/angular/api/utilities/gridformarray.md) · binds via the `[formArray]` input on `<tbw-grid>`.

```typescript
import { Component, inject, input, output } from '@angular/core';
import {
  FormArray, FormBuilder, FormControl, FormGroup,
  ReactiveFormsModule, Validators, AbstractControl
} from '@angular/forms';
import { Grid, TbwRenderer } from '@toolbox-web/grid-angular';
import { GridEditingDirective, GridFormArray, TbwEditor } from '@toolbox-web/grid-angular/features/editing';
// Custom validated input editor
@Component({
  selector: 'app-validated-input',
  standalone: true,
  imports: [ReactiveFormsModule, GridEditingDirective],
  template: `
    @if (control()) {
      <input
        [formControl]="control()"
        [class.is-invalid]="control()!.invalid && control()!.touched"
      />
      @if (control()!.invalid && control()!.touched) {
        <small class="error">{{ getErrorMessage() }}</small>
      }
    }
  `,
  styles: `
    .is-invalid { border-color: red; }
    .error { color: red; font-size: 0.8em; }
  `
})
export class ValidatedInputComponent {
  control = input<AbstractControl>();
  commit = output<string>();

  getErrorMessage(): string {
    const ctrl = this.control();
    if (ctrl?.hasError('required')) return 'Required';
    if (ctrl?.hasError('min')) return 'Value too low';
    return 'Invalid';
  }
}

@Component({
  imports: [
    Grid, GridFormArray, GridEditingDirective, TbwRenderer, TbwEditor,
    ReactiveFormsModule, ValidatedInputComponent
  ],
  template: `
    <form [formGroup]="form">
      <tbw-grid [formArray]="form.controls.employees" [gridConfig]="config" style="height: 400px; display: block;">
        <tbw-grid-column field="age" editable>
          <span *tbwRenderer="let value">{{ value }}</span>
          <!-- The 'control' gives you the FormControl for this cell -->
          <app-validated-input *tbwEditor="let value; control as ctrl" [control]="ctrl" />
        </tbw-grid-column>
      </tbw-grid>
    </form>

    <div class="validation-summary">
      <p>Form Valid: {{ form.valid }}</p>
      <p>Dirty: {{ form.controls.employees.dirty }}</p>
      <p>Touched: {{ form.controls.employees.touched }}</p>
      <p>Errors: {{ getFormErrors() | json }}</p>
    </div>
  `
})
export class FormArrayExample {
  private fb = inject(FormBuilder);

  form = this.fb.group({
    employees: this.fb.array([
      this.fb.group({
        name: ['Alice', Validators.required],
        age: [30, [Validators.required, Validators.min(18)]],
      }),
      this.fb.group({
        name: ['Bob', Validators.required],
        age: [25, [Validators.required, Validators.min(18)]],
      }),
    ])
  });

  config = {
    columns: [
      { field: 'name', header: 'Name', editable: true },
      { field: 'age', header: 'Age', editable: true },
    ],
    features: { editing: true },
  };

  getFormErrors(): string[] {
    const errors: string[] = [];
    this.form.controls.employees.controls.forEach((group, idx) => {
      Object.keys(group.controls).forEach(field => {
        const ctrl = group.get(field);
        if (ctrl?.errors) {
          errors.push(`Row ${idx}, ${field}: ${JSON.stringify(ctrl.errors)}`);
        }
      });
    });
    return errors;
  }
}
```

## Variable Row Heights with FormArray

When using variable row heights with FormArray, you **must** configure `rowId`. This is because `getRawValue()` returns new plain objects that don't match the original row references, breaking the WeakMap-based height cache.

```typescript
gridConfig: GridConfig = {
  // REQUIRED: Enables height cache to survive FormArray updates
  rowId: 'id',
  rowHeight: (row) => row.hasValidationErrors ? undefined : 32,
  columns: [/* ... */],
};
```

Without `rowId`, each `getRawValue()` call creates new objects, causing all row heights to be re-measured unnecessarily.

## Row-Level Validation

When using `FormArray` with `FormGroup`s, you can access row-level validation state via `getFormArrayContext()` (re-exported from [`GridFormArray`](/grid/angular/api/utilities/gridformarray.md)). The returned [`FormArrayContext`](/grid/angular/api/types/formarraycontext.md) exposes:

```typescript
import { getFormArrayContext } from '@toolbox-web/grid-angular/features/editing';

// Get validation context from grid element
const context = getFormArrayContext(gridElement);

if (context?.hasFormGroups) {
  // Row-level state
  const isRowValid = context.isRowValid(0);      // All controls valid?
  const isRowTouched = context.isRowTouched(0);  // Any control touched?
  const isRowDirty = context.isRowDirty(0);      // Any control changed?

  // Aggregated errors for a row
  const errors = context.getRowErrors(0);
  // Returns: { name: { required: true }, age: { min: { min: 18, actual: 15 } } }

  // Direct control access
  const rowGroup = context.getRowFormGroup(0);   // FormGroup for the row
  const cellCtrl = context.getControl(0, 'name'); // FormControl for one cell

  // Read-only data access
  const row = context.getRow(0);                 // Row object
  const allRows = context.getValue();            // Array of all row values

  // Programmatic mutation
  context.updateField(0, 'name', 'Alice');       // Patch one cell
}
```

## Editor Context Properties

When using `*tbwEditor`, the following context is available (see [`GridEditorContext`](/grid/angular/api/types/grideditorcontext.md) for the typed interface):

| Property        | Type                              | Description |
|-----------------|-----------------------------------|-------------|
| `$implicit`     | `TValue`                          | Cell value (bound by `*tbwEditor="let value"`) |
| `value`         | `TValue`                          | Cell value (explicit alias) |
| `row`           | `TRow`                            | Full row data object |
| `field`         | `string`                          | Field name being edited |
| `column`        | [`ColumnConfig`](/grid/api/core/interfaces/columnconfig.md) | Column configuration |
| `rowId`         | `string`                          | Stable row id from `getRowId` (empty string when none configured) |
| `onCommit`      | `(value: TValue) => void`         | Commit callback (rarely needed — see auto-wiring note below) |
| `onCancel`      | `() => void`                      | Cancel callback (rarely needed) |
| `updateRow`     | `(changes: Partial<TRow>) => void` | Update other fields in the same row while editing |
| `onValueChange` | `(cb) => void`                    | Subscribe to external value changes (e.g. from `updateRow` cascades) |
| `control`       | [`AbstractControl`](https://angular.dev/api/forms/AbstractControl) \| `undefined` | Cell `FormControl` (only when bound to `FormArray` + `FormGroup`) |

> **Auto-wiring:** the adapter listens for native `commit` / `cancel` `CustomEvent`s on the rendered component. If your editor dispatches them (or extends [`BaseGridEditor`](/grid/angular/base-classes.md) which does), you can omit the `(commit)="onCommit($event)"` binding entirely.

## Automatic Validation Syncing

When using `GridFormArray`, Angular's FormControl validation is **automatically synced** to the grid's visual invalid styling. This means:

1. **After a cell is edited**, if the FormControl is invalid, the cell shows a red border/background
2. **When the FormControl becomes valid**, the invalid styling is automatically cleared
3. **On row-commit**, if the FormGroup has invalid controls, the commit is **prevented** and the row reverts to its original values

This happens by default with `syncValidation="true"` (the default). You can disable it:

```html
<!-- Disable automatic validation sync if you want manual control -->
<tbw-grid [formArray]="rows" [syncValidation]="false" ... />
```

### How It Works

The `GridFormArray` directive listens to `cell-commit` events and checks the corresponding FormControl's validity. If invalid, it calls `EditingPlugin.setInvalid()` with a human-readable error message derived from Angular's validation errors.

Supported Angular validators are automatically translated to error messages:

| Validator | Generated Message |
|-----------|-------------------|
| `required` | "This field is required" |
| `minlength` | "Minimum length is X" |
| `maxlength` | "Maximum length is X" |
| `min` | "Minimum value is X" |
| `max` | "Maximum value is X" |
| `email` | "Invalid email address" |
| `pattern` | "Invalid format" |
| Custom | Uses `error.message` or "Validation error: key" |

### Custom Error Messages

For custom error messages, provide a `message` property in your validator's error object:

```typescript
// Custom validator with descriptive message
function customValidator(control: AbstractControl): ValidationErrors | null {
  if (!isValid(control.value)) {
    return {
      customError: {
        message: 'Please enter a valid XYZ format'
      }
    };
  }
  return null;
}
```

## CSS Classes

Angular Forms automatically adds validation classes to the grid element:

| Class | Description |
|-------|-------------|
| `.ng-valid` / `.ng-invalid` | Validation state |
| `.ng-pristine` / `.ng-dirty` | Edit state |
| `.ng-untouched` / `.ng-touched` | Touch state |
| `.form-disabled` | Added when control is disabled |

```css
tbw-grid.ng-invalid.ng-touched {
  border: 2px solid red;
}

tbw-grid.form-disabled {
  opacity: 0.6;
  pointer-events: none;
}
```

## Cell-Level Invalid Styling

When Angular validation fails, the grid visually highlights invalid cells using CSS custom properties:

```css
tbw-grid {
  /* Customize invalid cell appearance */
  --tbw-invalid-bg: #fef2f2;
  --tbw-invalid-border-color: #ef4444;
}
```

This integrates seamlessly with the EditingPlugin's validation system, meaning Angular's `Validators.required`, `Validators.email`, etc. automatically show visual feedback in the grid.

---

## Lazy Form Binding (GridLazyForm)

For large datasets, `GridFormArray` can be slow because it creates **all FormGroups upfront**. With 200 rows and 22 fields, that's 4,400 FormControl instances!

`GridLazyForm` solves this by creating FormGroups **on-demand** when editing starts—typically reducing control count by 100x.

> **Directive:** [`GridLazyForm`](/grid/angular/api/utilities/gridlazyform.md) · [`LazyFormFactory`](/grid/angular/api/types/lazyformfactory.md) · [`RowFormChangeEvent`](/grid/angular/api/types/rowformchangeevent.md)

### When to Use Each Directive

| Directive | Best For | FormGroups Created |
|-----------|----------|-------------------|
| `GridFormArray` | Small datasets (fewer than 50 rows), full-grid editing, Excel-like UX | All upfront |
| `GridLazyForm` | Large datasets (100+ rows), typical CRUD apps | Only when editing |

### Performance Comparison

| Rows | GridFormArray (22 fields) | GridLazyForm |
|------|--------------------------|--------------|
| 100  | 2,200 controls | ~22 controls |
| 500  | 11,000 controls | ~22 controls |
| 1,000 | 22,000 controls | ~22 controls |

### Basic Usage

```typescript
import { Component, inject, signal } from '@angular/core';
import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';
import { Grid } from '@toolbox-web/grid-angular';
import { GridEditingDirective, GridLazyForm, TbwEditor } from '@toolbox-web/grid-angular/features/editing';
interface Employee {
  id: number;
  firstName: string;
  lastName: string;
  salary: number;
}

@Component({
  imports: [Grid, GridLazyForm, GridEditingDirective, TbwEditor, ReactiveFormsModule],
  template: `
    <tbw-grid
      [rows]="employees()"
      [lazyForm]="createRowForm"
      [gridConfig]="gridConfig">

      <tbw-grid-column field="firstName">
        <input *tbwEditor="let _; control as ctrl"
               [formControl]="ctrl"
               [class.is-invalid]="ctrl?.invalid && ctrl?.touched" />
      </tbw-grid-column>

      <tbw-grid-column field="salary">
        <input *tbwEditor="let _; control as ctrl"
               type="number"
               [formControl]="ctrl" />
      </tbw-grid-column>
    </tbw-grid>
  `
})
export class LazyFormExample {
  private fb = inject(FormBuilder);

  employees = signal<Employee[]>([
    { id: 1, firstName: 'Alice', lastName: 'Smith', salary: 75000 },
    { id: 2, firstName: 'Bob', lastName: 'Jones', salary: 82000 },
  ]);

  // Factory called ONLY when a row enters edit mode
  createRowForm = (employee: Employee): FormGroup => this.fb.group({
    // Only include EDITABLE fields - skip read-only fields like 'id'
    firstName: [employee.firstName, Validators.required],
    lastName: [employee.lastName, [Validators.required, Validators.minLength(2)]],
    salary: [employee.salary, [Validators.required, Validators.min(0)]],
  });

  gridConfig = {
    columns: [
      { field: 'id', header: 'ID' },
      { field: 'firstName', header: 'First Name', editable: true },
      { field: 'lastName', header: 'Last Name', editable: true },
      { field: 'salary', header: 'Salary', editable: true, type: 'number' },
    ],
    features: { editing: true },
  };
}
```

### Configuration Options

| Input | Type | Default | Description |
|-------|------|---------|-------------|
| `[lazyForm]` | `(row: T) => FormGroup` | Required | Factory function to create FormGroups |
| `[syncValidation]` | `boolean` | `true` | Sync Angular validation to grid styling |
| `[keepFormGroups]` | `boolean` | `false` | Keep FormGroups cached after edit ends |

| Output | Type | Description |
|--------|------|-------------|
| `(rowFormChange)` | `RowFormChangeEvent` | Emitted when form values change |

### Form Factory Best Practices

```typescript
// ✅ Good: Only include editable fields
createRowForm = (row: Employee): FormGroup => this.fb.group({
  firstName: [row.firstName, Validators.required],
  lastName: [row.lastName],
  salary: [row.salary, [Validators.min(0)]],
});

// ❌ Bad: Including read-only fields wastes memory
createRowForm = (row: Employee): FormGroup => this.fb.group({
  id: [{ value: row.id, disabled: true }],  // Unnecessary!
  email: [{ value: row.email, disabled: true }],  // Unnecessary!
  firstName: [row.firstName],
  // ...
});
```

### Keeping FormGroups Between Edits

By default, FormGroups are cleaned up when a row exits edit mode. Set `[keepFormGroups]="true"` to preserve dirty/touched state:

```html
<!-- FormGroups persist between edit sessions -->
<tbw-grid
  [rows]="employees()"
  [lazyForm]="createRowForm"
  [keepFormGroups]="true"
  [gridConfig]="gridConfig">
</tbw-grid>
```

### Listening to Form Changes

The `(rowFormChange)` output emits a [`RowFormChangeEvent`](/grid/angular/api/types/rowformchangeevent.md) every time the row's `FormGroup` value or status changes. The event includes `rowIndex`, `rowId?`, `row`, `formGroup`, `values`, `valid`, and `dirty`.

```typescript
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { RowFormChangeEvent } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="employees()"
      [lazyForm]="createRowForm"
      (rowFormChange)="onFormChange($event)"
      [gridConfig]="gridConfig">
    </tbw-grid>

    <div *ngIf="lastChange">
      <p>Last edit: Row {{ lastChange.rowIndex }}</p>
      <p>Valid: {{ lastChange.valid }}</p>
      <p>Dirty: {{ lastChange.dirty }}</p>
    </div>
  `
})
export class FormChangeExample {
  lastChange: RowFormChangeEvent<Employee> | null = null;

  onFormChange(event: RowFormChangeEvent<Employee>) {
    this.lastChange = event;
    console.log('Form changed:', event.values);

    // Auto-save dirty, valid forms
    if (event.dirty && event.valid) {
      this.autoSave(event.row, event.values);
    }
  }
}
```

### Programmatic Access

```typescript
import { viewChild } from '@angular/core';
import { GridLazyForm } from '@toolbox-web/grid-angular/features/editing';

@Component({ /* ... */ })
export class MyComponent {
  lazyForm = viewChild.required(GridLazyForm<Employee>);

  validateBeforeSave() {
    // Validate all currently cached FormGroups
    if (!this.lazyForm().validateAll()) {
      console.log('Some rows are invalid');
      return false;
    }
    return true;
  }

  getEditedRows() {
    // Get all rows that have been edited
    const formGroups = this.lazyForm().getAllFormGroups();
    console.log('Edited rows:', formGroups.size);
    return formGroups;
  }

  resetAfterSave() {
    // Clear all cached FormGroups after successful save
    this.lazyForm().clearAllFormGroups();
  }
}
```

### Full-Grid Editing with FormArray

`GridFormArray` pairs naturally with `mode: 'grid'`—the spreadsheet-like editing mode where **all editable cells display their editors at once**.

```typescript
gridConfig = {
  columns: [
    { field: 'name', header: 'Name', editable: true },
    { field: 'age', header: 'Age', editable: true, type: 'number' },
  ],
  features: { editing: { mode: 'grid' } },
};
```

This enables:

- **All editors visible immediately** — no click-to-edit; every editable cell shows its input
- **Tab between cells** across the entire grid
- **Arrow-key navigation** — press Escape to leave an input, then navigate with arrow keys; press Enter to re-enter the input
- **Cell-level revert on Escape** — reverts the cell to its pre-edit value and resets the corresponding `FormControl`
- **Reactive validation syncing** — `GridFormArray` subscribes to each `FormControl`'s `statusChanges` so invalid styling updates in real time as the user types
- **Bulk validation before save** — call `form.valid` or inspect `FormArray`-level errors
- **FormArray-level operations** — `push`, `removeAt`, etc. update the grid automatically

#### How `GridFormArray` Handles Grid Mode

When `syncValidation` is enabled (the default) and the `EditingPlugin` is in `mode: 'grid'`:

1. **Initial validation** — pre-existing validation errors are shown as soon as the grid renders
2. **Reactive updates** — each `FormControl`'s `statusChanges` is subscribed so the grid marks/clears invalid cells automatically
3. **Escape (cell-cancel)** — the `cell-cancel` event resets the `FormControl` to its previous value, keeping Angular form state in sync

```typescript
@Component({
  imports: [Grid, GridFormArray, GridEditingDirective, TbwEditor, ReactiveFormsModule],
  template: `
    <form [formGroup]="form">
      <tbw-grid
        [formArray]="form.controls.employees"
        [gridConfig]="gridConfig"
        style="height: 400px; display: block;">
        <tbw-grid-column field="name" editable>
          <input *tbwEditor="let _; control as ctrl" [formControl]="ctrl" />
        </tbw-grid-column>
        <tbw-grid-column field="age" editable>
          <input *tbwEditor="let _; control as ctrl" type="number" [formControl]="ctrl" />
        </tbw-grid-column>
      </tbw-grid>
    </form>
    <button [disabled]="form.invalid" (click)="save()">Save All</button>
  `
})
export class GridModeFormArrayExample {
  private fb = inject(FormBuilder);

  form = this.fb.group({
    employees: this.fb.array([
      this.fb.group({ name: ['Alice', Validators.required], age: [30, [Validators.required, Validators.min(18)]] }),
      this.fb.group({ name: ['Bob', Validators.required], age: [25, [Validators.required, Validators.min(18)]] }),
    ])
  });

  gridConfig = {
    columns: [
      { field: 'name', header: 'Name', editable: true },
      { field: 'age', header: 'Age', editable: true, type: 'number' },
    ],
    features: { editing: { mode: 'grid' } },
  };

  save() {
    console.log('Saving:', this.form.controls.employees.getRawValue());
  }
}
```

For typical single-row CRUD workflows, `GridLazyForm` with the default `mode: 'row'` remains the more efficient choice.

---

## API Reference



The complete generated TypeDoc reference is not inlined above. Every symbol has a plain-markdown companion — fetch any link below (or append `.md` to its page URL).

### Core

- [A11yconfig](https://toolboxjs.com/grid/api/core/interfaces/a11yconfig.md)
- [A11ymessages](https://toolboxjs.com/grid/api/core/interfaces/a11ymessages.md)
- [Aggregatorref](https://toolboxjs.com/grid/api/core/types/aggregatorref.md)
- [Animationconfig](https://toolboxjs.com/grid/api/core/interfaces/animationconfig.md)
- [Animationmode](https://toolboxjs.com/grid/api/core/types/animationmode.md)
- [Animationstyle](https://toolboxjs.com/grid/api/core/types/animationstyle.md)
- [Basecolumnconfig](https://toolboxjs.com/grid/api/core/interfaces/basecolumnconfig.md)
- [Builtinsort](https://toolboxjs.com/grid/api/core/functions/builtinsort.md)
- [Cellactivatedetail](https://toolboxjs.com/grid/api/core/interfaces/cellactivatedetail.md)
- [Cellactivatetrigger](https://toolboxjs.com/grid/api/core/types/cellactivatetrigger.md)
- [Cellchangedetail](https://toolboxjs.com/grid/api/core/interfaces/cellchangedetail.md)
- [Cellclickdetail](https://toolboxjs.com/grid/api/core/interfaces/cellclickdetail.md)
- [Cellrendercontext](https://toolboxjs.com/grid/api/core/interfaces/cellrendercontext.md)
- [Columnconfig](https://toolboxjs.com/grid/api/core/interfaces/columnconfig.md)
- [Columnconfigmap](https://toolboxjs.com/grid/api/core/types/columnconfigmap.md)
- [Columneditorcontext](https://toolboxjs.com/grid/api/core/interfaces/columneditorcontext.md)
- [Columneditorspec](https://toolboxjs.com/grid/api/core/types/columneditorspec.md)
- [Columninferencemode](https://toolboxjs.com/grid/api/core/types/columninferencemode.md)
- [Columnresizedetail](https://toolboxjs.com/grid/api/core/interfaces/columnresizedetail.md)
- [Columnresizeresetdetail](https://toolboxjs.com/grid/api/core/interfaces/columnresizeresetdetail.md)
- [Columnsortstate](https://toolboxjs.com/grid/api/core/interfaces/columnsortstate.md)
- [Columnstate](https://toolboxjs.com/grid/api/core/interfaces/columnstate.md)
- [Columntype](https://toolboxjs.com/grid/api/core/types/columntype.md)
- [Columnviewrenderer](https://toolboxjs.com/grid/api/core/types/columnviewrenderer.md)
- [Creategrid](https://toolboxjs.com/grid/api/core/functions/creategrid.md)
- [Datachangedetail](https://toolboxjs.com/grid/api/core/interfaces/datachangedetail.md)
- [Datagridcustomevent](https://toolboxjs.com/grid/api/core/types/datagridcustomevent.md)
- [Datagridelement](https://toolboxjs.com/grid/api/core/classes/datagridelement.md)
- [Datagrideventmap](https://toolboxjs.com/grid/api/core/interfaces/datagrideventmap.md)
- [Defaultcomparator](https://toolboxjs.com/grid/api/core/functions/defaultcomparator.md)
- [Dgeventname](https://toolboxjs.com/grid/api/core/types/dgeventname.md)
- [Emptycontext](https://toolboxjs.com/grid/api/core/interfaces/emptycontext.md)
- [Emptyoverlay](https://toolboxjs.com/grid/api/core/types/emptyoverlay.md)
- [Emptyrenderer](https://toolboxjs.com/grid/api/core/types/emptyrenderer.md)
- [Expandcollapseanimation](https://toolboxjs.com/grid/api/core/types/expandcollapseanimation.md)
- [Featureconfig](https://toolboxjs.com/grid/api/core/interfaces/featureconfig.md)
- [Fitmode](https://toolboxjs.com/grid/api/core/types/fitmode.md)
- [Gridcolumnstate](https://toolboxjs.com/grid/api/core/interfaces/gridcolumnstate.md)
- [Gridconfig](https://toolboxjs.com/grid/api/core/interfaces/gridconfig.md)
- [Gridicons](https://toolboxjs.com/grid/api/core/interfaces/gridicons.md)
- [Headercellcontext](https://toolboxjs.com/grid/api/core/interfaces/headercellcontext.md)
- [Headercontentdefinition](https://toolboxjs.com/grid/api/core/types/headercontentdefinition.md)
- [Headerlabelcontext](https://toolboxjs.com/grid/api/core/interfaces/headerlabelcontext.md)
- [Headerlabelrenderer](https://toolboxjs.com/grid/api/core/types/headerlabelrenderer.md)
- [Headerrenderer](https://toolboxjs.com/grid/api/core/types/headerrenderer.md)
- [Iconvalue](https://toolboxjs.com/grid/api/core/types/iconvalue.md)
- [Inferredcolumnresult](https://toolboxjs.com/grid/api/core/interfaces/inferredcolumnresult.md)
- [Invalidateaccessorcache](https://toolboxjs.com/grid/api/core/functions/invalidateaccessorcache.md)
- [Loadingcontext](https://toolboxjs.com/grid/api/core/interfaces/loadingcontext.md)
- [Loadingrenderer](https://toolboxjs.com/grid/api/core/types/loadingrenderer.md)
- [Loadingsize](https://toolboxjs.com/grid/api/core/types/loadingsize.md)
- [Plugineventname](https://toolboxjs.com/grid/api/core/types/plugineventname.md)
- [Primitivecolumntype](https://toolboxjs.com/grid/api/core/types/primitivecolumntype.md)
- [Publicgrid](https://toolboxjs.com/grid/api/core/interfaces/publicgrid.md)
- [Querygrid](https://toolboxjs.com/grid/api/core/functions/querygrid.md)
- [Renderdetail](https://toolboxjs.com/grid/api/core/interfaces/renderdetail.md)
- [Resolvecellvalue](https://toolboxjs.com/grid/api/core/functions/resolvecellvalue.md)
- [Rowanimationtype](https://toolboxjs.com/grid/api/core/types/rowanimationtype.md)
- [Rowclickdetail](https://toolboxjs.com/grid/api/core/interfaces/rowclickdetail.md)
- [Rowgrouprenderconfig](https://toolboxjs.com/grid/api/core/interfaces/rowgrouprenderconfig.md)
- [Rowtransaction](https://toolboxjs.com/grid/api/core/interfaces/rowtransaction.md)
- [Rowupdate](https://toolboxjs.com/grid/api/core/interfaces/rowupdate.md)
- [Scrolltorowoptions](https://toolboxjs.com/grid/api/core/interfaces/scrolltorowoptions.md)
- [Shellconfig](https://toolboxjs.com/grid/api/core/types/shellconfig.md)
- [Shellheaderconfig](https://toolboxjs.com/grid/api/core/types/shellheaderconfig.md)
- [Sortchangedetail](https://toolboxjs.com/grid/api/core/interfaces/sortchangedetail.md)
- [Sorthandler](https://toolboxjs.com/grid/api/core/types/sorthandler.md)
- [Sortstate](https://toolboxjs.com/grid/api/core/interfaces/sortstate.md)
- [Tbwscrolldetail](https://toolboxjs.com/grid/api/core/interfaces/tbwscrolldetail.md)
- [Toolbarcontentdefinition](https://toolboxjs.com/grid/api/core/types/toolbarcontentdefinition.md)
- [Toolpanelconfig](https://toolboxjs.com/grid/api/core/types/toolpanelconfig.md)
- [Toolpaneldefinition](https://toolboxjs.com/grid/api/core/types/toolpaneldefinition.md)
- [Transactionresult](https://toolboxjs.com/grid/api/core/interfaces/transactionresult.md)
- [Typedefault](https://toolboxjs.com/grid/api/core/interfaces/typedefault.md)
- [Updatesource](https://toolboxjs.com/grid/api/core/types/updatesource.md)

### Plugins

- [Aggfunc](https://toolboxjs.com/grid/plugins/pivot/types/aggfunc.md)
- [Aggregationrowconfig](https://toolboxjs.com/grid/plugins/pinned-rows/interfaces/aggregationrowconfig.md)
- [Aggregationslot](https://toolboxjs.com/grid/plugins/pinned-rows/types/aggregationslot.md)
- [Aggregatorconfig](https://toolboxjs.com/grid/plugins/pinned-rows/interfaces/aggregatorconfig.md)
- [Aggregatordefinition](https://toolboxjs.com/grid/plugins/pinned-rows/types/aggregatordefinition.md)
- [Aggregatorformatter](https://toolboxjs.com/grid/plugins/pinned-rows/types/aggregatorformatter.md)
- [Aggregatormap](https://toolboxjs.com/grid/plugins/grouping-rows/types/aggregatormap.md)
- [Baselinescaptureddetail](https://toolboxjs.com/grid/plugins/editing/interfaces/baselinescaptureddetail.md)
- [Beforeeditclosedetail](https://toolboxjs.com/grid/plugins/editing/interfaces/beforeeditclosedetail.md)
- [Blankmode](https://toolboxjs.com/grid/plugins/filtering/types/blankmode.md)
- [Breakpointconfig](https://toolboxjs.com/grid/plugins/responsive/interfaces/breakpointconfig.md)
- [Cellcanceldetail](https://toolboxjs.com/grid/plugins/editing/interfaces/cellcanceldetail.md)
- [Cellcommitdetail](https://toolboxjs.com/grid/plugins/editing/interfaces/cellcommitdetail.md)
- [Cellrange](https://toolboxjs.com/grid/plugins/selection/interfaces/cellrange.md)
- [Changedrowsresetdetail](https://toolboxjs.com/grid/plugins/editing/interfaces/changedrowsresetdetail.md)
- [Clipboardconfig](https://toolboxjs.com/grid/plugins/clipboard/interfaces/clipboardconfig.md)
- [Clipboardplugin](https://toolboxjs.com/grid/plugins/clipboard/classes/clipboardplugin.md)
- [Columngroup](https://toolboxjs.com/grid/plugins/grouping-columns/interfaces/columngroup.md)
- [Columngroupdefinition](https://toolboxjs.com/grid/plugins/grouping-columns/interfaces/columngroupdefinition.md)
- [Columngroupinfo](https://toolboxjs.com/grid/plugins/visibility/interfaces/columngroupinfo.md)
- [Columnmovedetail](https://toolboxjs.com/grid/plugins/reorder-columns/interfaces/columnmovedetail.md)
- [Columnreorderrequestdetail](https://toolboxjs.com/grid/plugins/visibility/interfaces/columnreorderrequestdetail.md)
- [Columnvirtualizationconfig](https://toolboxjs.com/grid/plugins/column-virtualization/interfaces/columnvirtualizationconfig.md)
- [Columnvirtualizationplugin](https://toolboxjs.com/grid/plugins/column-virtualization/classes/columnvirtualizationplugin.md)
- [Columnvisibilitydetail](https://toolboxjs.com/grid/plugins/visibility/interfaces/columnvisibilitydetail.md)
- [Compoundeditaction](https://toolboxjs.com/grid/plugins/undo-redo/interfaces/compoundeditaction.md)
- [Contextmenuconfig](https://toolboxjs.com/grid/plugins/context-menu/interfaces/contextmenuconfig.md)
- [Contextmenuitem](https://toolboxjs.com/grid/plugins/context-menu/interfaces/contextmenuitem.md)
- [Contextmenuopendetail](https://toolboxjs.com/grid/plugins/context-menu/interfaces/contextmenuopendetail.md)
- [Contextmenuparams](https://toolboxjs.com/grid/plugins/context-menu/interfaces/contextmenuparams.md)
- [Contextmenuplugin](https://toolboxjs.com/grid/plugins/context-menu/classes/contextmenuplugin.md)
- [Copydetail](https://toolboxjs.com/grid/plugins/clipboard/interfaces/copydetail.md)
- [Copyoptions](https://toolboxjs.com/grid/plugins/clipboard/interfaces/copyoptions.md)
- [Csvoptions](https://toolboxjs.com/grid/plugins/export/interfaces/csvoptions.md)
- [Customaggfunc](https://toolboxjs.com/grid/plugins/pivot/types/customaggfunc.md)
- [Datarequestmodel](https://toolboxjs.com/grid/plugins/server-side/interfaces/datarequestmodel.md)
- [Datarowmodelitem](https://toolboxjs.com/grid/plugins/grouping-rows/interfaces/datarowmodelitem.md)
- [Datasourcechildrendetail](https://toolboxjs.com/grid/plugins/server-side/interfaces/datasourcechildrendetail.md)
- [Datasourcedatadetail](https://toolboxjs.com/grid/plugins/server-side/interfaces/datasourcedatadetail.md)
- [Datasourceerrordetail](https://toolboxjs.com/grid/plugins/server-side/interfaces/datasourceerrordetail.md)
- [Datasourceloadingdetail](https://toolboxjs.com/grid/plugins/server-side/interfaces/datasourceloadingdetail.md)
- [Dateeditorparams](https://toolboxjs.com/grid/plugins/editing/interfaces/dateeditorparams.md)
- [Defaulteditorfor](https://toolboxjs.com/grid/plugins/editing/functions/defaulteditorfor.md)
- [Defaultexpandedvalue](https://toolboxjs.com/grid/plugins/grouping-rows/types/defaultexpandedvalue.md)
- [Defaultpastehandler](https://toolboxjs.com/grid/plugins/clipboard/functions/defaultpastehandler.md)
- [Detailexpanddetail](https://toolboxjs.com/grid/plugins/master-detail/interfaces/detailexpanddetail.md)
- [Dirtychangedetail](https://toolboxjs.com/grid/plugins/editing/interfaces/dirtychangedetail.md)
- [Dirtyrowentry](https://toolboxjs.com/grid/plugins/editing/interfaces/dirtyrowentry.md)
- [Editaction](https://toolboxjs.com/grid/plugins/undo-redo/interfaces/editaction.md)
- [Editclosedetail](https://toolboxjs.com/grid/plugins/editing/interfaces/editclosedetail.md)
- [Editingconfig](https://toolboxjs.com/grid/plugins/editing/interfaces/editingconfig.md)
- [Editingplugin](https://toolboxjs.com/grid/plugins/editing/classes/editingplugin.md)
- [Editopendetail](https://toolboxjs.com/grid/plugins/editing/interfaces/editopendetail.md)
- [Editorparams](https://toolboxjs.com/grid/plugins/editing/types/editorparams.md)
- [Excelborder](https://toolboxjs.com/grid/plugins/export/interfaces/excelborder.md)
- [Excelcellstyle](https://toolboxjs.com/grid/plugins/export/interfaces/excelcellstyle.md)
- [Excelstyleconfig](https://toolboxjs.com/grid/plugins/export/interfaces/excelstyleconfig.md)
- [Exportcompletedetail](https://toolboxjs.com/grid/plugins/export/interfaces/exportcompletedetail.md)
- [Exportconfig](https://toolboxjs.com/grid/plugins/export/interfaces/exportconfig.md)
- [Exportformat](https://toolboxjs.com/grid/plugins/export/types/exportformat.md)
- [Exportmode](https://toolboxjs.com/grid/plugins/export/types/exportmode.md)
- [Exportparams](https://toolboxjs.com/grid/plugins/export/interfaces/exportparams.md)
- [Exportplugin](https://toolboxjs.com/grid/plugins/export/classes/exportplugin.md)
- [Fetchchildrenquery](https://toolboxjs.com/grid/plugins/server-side/interfaces/fetchchildrenquery.md)
- [Filterchangedetail](https://toolboxjs.com/grid/plugins/filtering/interfaces/filterchangedetail.md)
- [Filterconfig](https://toolboxjs.com/grid/plugins/filtering/interfaces/filterconfig.md)
- [Filteredcountpanel](https://toolboxjs.com/grid/plugins/pinned-rows/functions/filteredcountpanel.md)
- [Filterhandler](https://toolboxjs.com/grid/plugins/filtering/types/filterhandler.md)
- [Filteringplugin](https://toolboxjs.com/grid/plugins/filtering/classes/filteringplugin.md)
- [Filtermodel](https://toolboxjs.com/grid/plugins/filtering/interfaces/filtermodel.md)
- [Filteroperator](https://toolboxjs.com/grid/plugins/filtering/types/filteroperator.md)
- [Filterpanelparams](https://toolboxjs.com/grid/plugins/filtering/interfaces/filterpanelparams.md)
- [Filterpanelrenderer](https://toolboxjs.com/grid/plugins/filtering/types/filterpanelrenderer.md)
- [Filterparams](https://toolboxjs.com/grid/plugins/filtering/interfaces/filterparams.md)
- [Filtertype](https://toolboxjs.com/grid/plugins/filtering/types/filtertype.md)
- [Filtervalueshandler](https://toolboxjs.com/grid/plugins/filtering/types/filtervalueshandler.md)
- [Flattenedtreerow](https://toolboxjs.com/grid/plugins/tree/interfaces/flattenedtreerow.md)
- [Formatcsvparams](https://toolboxjs.com/grid/plugins/export/types/formatcsvparams.md)
- [Formatexcelparams](https://toolboxjs.com/grid/plugins/export/types/formatexcelparams.md)
- [Getchildrowsparams](https://toolboxjs.com/grid/plugins/server-side/interfaces/getchildrowsparams.md)
- [Getchildrowsresult](https://toolboxjs.com/grid/plugins/server-side/interfaces/getchildrowsresult.md)
- [Getrowsparams](https://toolboxjs.com/grid/plugins/server-side/interfaces/getrowsparams.md)
- [Getrowsresult](https://toolboxjs.com/grid/plugins/server-side/interfaces/getrowsresult.md)
- [Groupcollapsedetail](https://toolboxjs.com/grid/plugins/grouping-rows/interfaces/groupcollapsedetail.md)
- [Groupdefinition](https://toolboxjs.com/grid/plugins/grouping-rows/interfaces/groupdefinition.md)
- [Groupexpanddetail](https://toolboxjs.com/grid/plugins/grouping-rows/interfaces/groupexpanddetail.md)
- [Groupheaderrenderparams](https://toolboxjs.com/grid/plugins/grouping-columns/interfaces/groupheaderrenderparams.md)
- [Groupingcolumnsconfig](https://toolboxjs.com/grid/plugins/grouping-columns/interfaces/groupingcolumnsconfig.md)
- [Groupingcolumnsplugin](https://toolboxjs.com/grid/plugins/grouping-columns/classes/groupingcolumnsplugin.md)
- [Groupingrowsconfig](https://toolboxjs.com/grid/plugins/grouping-rows/interfaces/groupingrowsconfig.md)
- [Groupingrowsplugin](https://toolboxjs.com/grid/plugins/grouping-rows/classes/groupingrowsplugin.md)
- [Grouprowmodelitem](https://toolboxjs.com/grid/plugins/grouping-rows/interfaces/grouprowmodelitem.md)
- [Grouprowrenderparams](https://toolboxjs.com/grid/plugins/grouping-rows/interfaces/grouprowrenderparams.md)
- [Groupstate](https://toolboxjs.com/grid/plugins/grouping-rows/interfaces/groupstate.md)
- [Grouptoggledetail](https://toolboxjs.com/grid/plugins/grouping-rows/interfaces/grouptoggledetail.md)
- [Headercontentdefinition](https://toolboxjs.com/grid/plugins/shell/interfaces/headercontentdefinition.md)
- [Headercontextmenuitem](https://toolboxjs.com/grid/plugins/context-menu/interfaces/headercontextmenuitem.md)
- [Hiddencolumnconfig](https://toolboxjs.com/grid/plugins/responsive/types/hiddencolumnconfig.md)
- [Masterdetailconfig](https://toolboxjs.com/grid/plugins/master-detail/interfaces/masterdetailconfig.md)
- [Masterdetailplugin](https://toolboxjs.com/grid/plugins/master-detail/classes/masterdetailplugin.md)
- [Multisortchangedetail](https://toolboxjs.com/grid/plugins/multi-sort/interfaces/multisortchangedetail.md)
- [Multisortconfig](https://toolboxjs.com/grid/plugins/multi-sort/interfaces/multisortconfig.md)
- [Multisortplugin](https://toolboxjs.com/grid/plugins/multi-sort/classes/multisortplugin.md)
- [Numbereditorparams](https://toolboxjs.com/grid/plugins/editing/interfaces/numbereditorparams.md)
- [Opentoolpaneloptions](https://toolboxjs.com/grid/plugins/shell/interfaces/opentoolpaneloptions.md)
- [Panelrender](https://toolboxjs.com/grid/plugins/pinned-rows/types/panelrender.md)
- [Panelslot](https://toolboxjs.com/grid/plugins/pinned-rows/interfaces/panelslot.md)
- [Panelzone](https://toolboxjs.com/grid/plugins/pinned-rows/types/panelzone.md)
- [Pastedetail](https://toolboxjs.com/grid/plugins/clipboard/interfaces/pastedetail.md)
- [Pastehandler](https://toolboxjs.com/grid/plugins/clipboard/types/pastehandler.md)
- [Pastetarget](https://toolboxjs.com/grid/plugins/clipboard/interfaces/pastetarget.md)
- [Pinnedcolumnsconfig](https://toolboxjs.com/grid/plugins/pinned-columns/interfaces/pinnedcolumnsconfig.md)
- [Pinnedcolumnsplugin](https://toolboxjs.com/grid/plugins/pinned-columns/classes/pinnedcolumnsplugin.md)
- [Pinnedposition](https://toolboxjs.com/grid/plugins/pinned-columns/types/pinnedposition.md)
- [Pinnedrowsconfig](https://toolboxjs.com/grid/plugins/pinned-rows/interfaces/pinnedrowsconfig.md)
- [Pinnedrowscontext](https://toolboxjs.com/grid/plugins/pinned-rows/interfaces/pinnedrowscontext.md)
- [Pinnedrowslot](https://toolboxjs.com/grid/plugins/pinned-rows/types/pinnedrowslot.md)
- [Pinnedrowspanel](https://toolboxjs.com/grid/plugins/pinned-rows/interfaces/pinnedrowspanel.md)
- [Pinnedrowsplugin](https://toolboxjs.com/grid/plugins/pinned-rows/classes/pinnedrowsplugin.md)
- [Pinnedrowsposition](https://toolboxjs.com/grid/plugins/pinned-rows/types/pinnedrowsposition.md)
- [Pivotconfig](https://toolboxjs.com/grid/plugins/pivot/interfaces/pivotconfig.md)
- [Pivotconfigchangedetail](https://toolboxjs.com/grid/plugins/pivot/interfaces/pivotconfigchangedetail.md)
- [Pivotdatarow](https://toolboxjs.com/grid/plugins/pivot/types/pivotdatarow.md)
- [Pivotdefaultexpandedvalue](https://toolboxjs.com/grid/plugins/pivot/types/pivotdefaultexpandedvalue.md)
- [Pivotplugin](https://toolboxjs.com/grid/plugins/pivot/classes/pivotplugin.md)
- [Pivotresult](https://toolboxjs.com/grid/plugins/pivot/interfaces/pivotresult.md)
- [Pivotrow](https://toolboxjs.com/grid/plugins/pivot/interfaces/pivotrow.md)
- [Pivotsortconfig](https://toolboxjs.com/grid/plugins/pivot/interfaces/pivotsortconfig.md)
- [Pivotsortdir](https://toolboxjs.com/grid/plugins/pivot/types/pivotsortdir.md)
- [Pivotstatechangedetail](https://toolboxjs.com/grid/plugins/pivot/interfaces/pivotstatechangedetail.md)
- [Pivottoggledetail](https://toolboxjs.com/grid/plugins/pivot/interfaces/pivottoggledetail.md)
- [Pivotvaluedisplaymode](https://toolboxjs.com/grid/plugins/pivot/types/pivotvaluedisplaymode.md)
- [Pivotvaluefield](https://toolboxjs.com/grid/plugins/pivot/interfaces/pivotvaluefield.md)
- [Printcompletedetail](https://toolboxjs.com/grid/plugins/print/interfaces/printcompletedetail.md)
- [Printconfig](https://toolboxjs.com/grid/plugins/print/interfaces/printconfig.md)
- [Printgridisolated](https://toolboxjs.com/grid/plugins/print/functions/printgridisolated.md)
- [Printisolatedoptions](https://toolboxjs.com/grid/plugins/print/interfaces/printisolatedoptions.md)
- [Printorientation](https://toolboxjs.com/grid/plugins/print/types/printorientation.md)
- [Printparams](https://toolboxjs.com/grid/plugins/print/interfaces/printparams.md)
- [Printplugin](https://toolboxjs.com/grid/plugins/print/classes/printplugin.md)
- [Printstartdetail](https://toolboxjs.com/grid/plugins/print/interfaces/printstartdetail.md)
- [Renderrow](https://toolboxjs.com/grid/plugins/grouping-rows/types/renderrow.md)
- [Reorderanimation](https://toolboxjs.com/grid/plugins/reorder-columns/types/reorderanimation.md)
- [Reorderconfig](https://toolboxjs.com/grid/plugins/reorder-columns/interfaces/reorderconfig.md)
- [Reorderplugin](https://toolboxjs.com/grid/plugins/reorder-columns/classes/reorderplugin.md)
- [Responsivechangedetail](https://toolboxjs.com/grid/plugins/responsive/interfaces/responsivechangedetail.md)
- [Responsiveplugin](https://toolboxjs.com/grid/plugins/responsive/classes/responsiveplugin.md)
- [Responsivepluginconfig](https://toolboxjs.com/grid/plugins/responsive/interfaces/responsivepluginconfig.md)
- [Rowcommitdetail](https://toolboxjs.com/grid/plugins/editing/interfaces/rowcommitdetail.md)
- [Rowcountpanel](https://toolboxjs.com/grid/plugins/pinned-rows/functions/rowcountpanel.md)
- [Rowdragdropconfig](https://toolboxjs.com/grid/plugins/row-drag-drop/interfaces/rowdragdropconfig.md)
- [Rowdragenddetail](https://toolboxjs.com/grid/plugins/row-drag-drop/interfaces/rowdragenddetail.md)
- [Rowdragpayload](https://toolboxjs.com/grid/plugins/row-drag-drop/interfaces/rowdragpayload.md)
- [Rowdragstartdetail](https://toolboxjs.com/grid/plugins/row-drag-drop/interfaces/rowdragstartdetail.md)
- [Rowdropdetail](https://toolboxjs.com/grid/plugins/row-drag-drop/interfaces/rowdropdetail.md)
- [Rowmovedetail](https://toolboxjs.com/grid/plugins/row-drag-drop/interfaces/rowmovedetail.md)
- [Rowreorderconfig](https://toolboxjs.com/grid/plugins/reorder-rows/types/rowreorderconfig.md)
- [Rowreorderplugin](https://toolboxjs.com/grid/plugins/reorder-rows/classes/rowreorderplugin.md)
- [Rowtransferdetail](https://toolboxjs.com/grid/plugins/row-drag-drop/interfaces/rowtransferdetail.md)
- [Selectablecallback](https://toolboxjs.com/grid/plugins/selection/types/selectablecallback.md)
- [Selectedcountpanel](https://toolboxjs.com/grid/plugins/pinned-rows/functions/selectedcountpanel.md)
- [Selecteditorparams](https://toolboxjs.com/grid/plugins/editing/interfaces/selecteditorparams.md)
- [Selectionaxis](https://toolboxjs.com/grid/plugins/selection/types/selectionaxis.md)
- [Selectionchangedetail](https://toolboxjs.com/grid/plugins/selection/interfaces/selectionchangedetail.md)
- [Selectionconfig](https://toolboxjs.com/grid/plugins/selection/interfaces/selectionconfig.md)
- [Selectionmode](https://toolboxjs.com/grid/plugins/selection/types/selectionmode.md)
- [Selectionplugin](https://toolboxjs.com/grid/plugins/selection/classes/selectionplugin.md)
- [Selectionresult](https://toolboxjs.com/grid/plugins/selection/interfaces/selectionresult.md)
- [Selectiontrigger](https://toolboxjs.com/grid/plugins/selection/types/selectiontrigger.md)
- [Serversideconfig](https://toolboxjs.com/grid/plugins/server-side/interfaces/serversideconfig.md)
- [Serversidedatasource](https://toolboxjs.com/grid/plugins/server-side/interfaces/serversidedatasource.md)
- [Serversideplugin](https://toolboxjs.com/grid/plugins/server-side/classes/serversideplugin.md)
- [Shellconfig](https://toolboxjs.com/grid/plugins/shell/interfaces/shellconfig.md)
- [Shellheaderconfig](https://toolboxjs.com/grid/plugins/shell/interfaces/shellheaderconfig.md)
- [Shellplugin](https://toolboxjs.com/grid/plugins/shell/classes/shellplugin.md)
- [Sortmodel](https://toolboxjs.com/grid/plugins/multi-sort/interfaces/sortmodel.md)
- [Stickypredicate](https://toolboxjs.com/grid/plugins/sticky-rows/types/stickypredicate.md)
- [Stickyrowsconfig](https://toolboxjs.com/grid/plugins/sticky-rows/interfaces/stickyrowsconfig.md)
- [Stickyrowsmode](https://toolboxjs.com/grid/plugins/sticky-rows/types/stickyrowsmode.md)
- [Stickyrowsplugin](https://toolboxjs.com/grid/plugins/sticky-rows/classes/stickyrowsplugin.md)
- [Subscribable](https://toolboxjs.com/grid/plugins/server-side/interfaces/subscribable.md)
- [Texteditorparams](https://toolboxjs.com/grid/plugins/editing/interfaces/texteditorparams.md)
- [Toolbarcontentdefinition](https://toolboxjs.com/grid/plugins/shell/interfaces/toolbarcontentdefinition.md)
- [Toolpanelconfig](https://toolboxjs.com/grid/plugins/shell/interfaces/toolpanelconfig.md)
- [Toolpaneldefinition](https://toolboxjs.com/grid/plugins/shell/interfaces/toolpaneldefinition.md)
- [Tooltipconfig](https://toolboxjs.com/grid/plugins/tooltip/interfaces/tooltipconfig.md)
- [Tooltipplugin](https://toolboxjs.com/grid/plugins/tooltip/classes/tooltipplugin.md)
- [Treeconfig](https://toolboxjs.com/grid/plugins/tree/interfaces/treeconfig.md)
- [Treeexpanddetail](https://toolboxjs.com/grid/plugins/tree/interfaces/treeexpanddetail.md)
- [Treeplugin](https://toolboxjs.com/grid/plugins/tree/classes/treeplugin.md)
- [Treerow](https://toolboxjs.com/grid/plugins/tree/types/treerow.md)
- [Undoredoaction](https://toolboxjs.com/grid/plugins/undo-redo/types/undoredoaction.md)
- [Undoredoconfig](https://toolboxjs.com/grid/plugins/undo-redo/interfaces/undoredoconfig.md)
- [Undoredodetail](https://toolboxjs.com/grid/plugins/undo-redo/interfaces/undoredodetail.md)
- [Undoredoplugin](https://toolboxjs.com/grid/plugins/undo-redo/classes/undoredoplugin.md)
- [Viewportmappingquery](https://toolboxjs.com/grid/plugins/server-side/interfaces/viewportmappingquery.md)
- [Viewportmappingresponse](https://toolboxjs.com/grid/plugins/server-side/interfaces/viewportmappingresponse.md)
- [Visibilityconfig](https://toolboxjs.com/grid/plugins/visibility/interfaces/visibilityconfig.md)
- [Visibilityplugin](https://toolboxjs.com/grid/plugins/visibility/classes/visibilityplugin.md)
- [Zonedpanelrender](https://toolboxjs.com/grid/plugins/pinned-rows/interfaces/zonedpanelrender.md)

### Plugin Development

- [Aftercellrendercontext](https://toolboxjs.com/grid/api/plugin-development/interfaces/aftercellrendercontext.md)
- [Afterrowrendercontext](https://toolboxjs.com/grid/api/plugin-development/interfaces/afterrowrendercontext.md)
- [Basegridplugin](https://toolboxjs.com/grid/api/plugin-development/classes/basegridplugin.md)
- [Cellcontext](https://toolboxjs.com/grid/api/plugin-development/interfaces/cellcontext.md)
- [Cellmouseevent](https://toolboxjs.com/grid/api/plugin-development/interfaces/cellmouseevent.md)
- [Collectheaderrowscontext](https://toolboxjs.com/grid/api/plugin-development/interfaces/collectheaderrowscontext.md)
- [Computescrollmapping](https://toolboxjs.com/grid/api/plugin-development/functions/computescrollmapping.md)
- [Datagridelement Pluginapi](https://toolboxjs.com/grid/api/plugin-development/classes/datagridelement-pluginapi.md)
- [Editorexeccontext](https://toolboxjs.com/grid/api/plugin-development/interfaces/editorexeccontext.md)
- [Evalcontext](https://toolboxjs.com/grid/api/plugin-development/interfaces/evalcontext.md)
- [Eventdefinition](https://toolboxjs.com/grid/api/plugin-development/interfaces/eventdefinition.md)
- [Fromvirtualscrolltop](https://toolboxjs.com/grid/api/plugin-development/functions/fromvirtualscrolltop.md)
- [Gridclassname](https://toolboxjs.com/grid/api/plugin-development/types/gridclassname.md)
- [Gridcssvar](https://toolboxjs.com/grid/api/plugin-development/types/gridcssvar.md)
- [Griddataattr](https://toolboxjs.com/grid/api/plugin-development/types/griddataattr.md)
- [Gridplugin](https://toolboxjs.com/grid/api/plugin-development/interfaces/gridplugin.md)
- [Headerrowcell](https://toolboxjs.com/grid/api/plugin-development/interfaces/headerrowcell.md)
- [Headerrowcontribution](https://toolboxjs.com/grid/api/plugin-development/interfaces/headerrowcontribution.md)
- [Internalgrid](https://toolboxjs.com/grid/api/plugin-development/interfaces/internalgrid.md)
- [Plugindependency](https://toolboxjs.com/grid/api/plugin-development/interfaces/plugindependency.md)
- [Pluginmanifest](https://toolboxjs.com/grid/api/plugin-development/interfaces/pluginmanifest.md)
- [Pluginquery](https://toolboxjs.com/grid/api/plugin-development/interfaces/pluginquery.md)
- [Querydefinition](https://toolboxjs.com/grid/api/plugin-development/interfaces/querydefinition.md)
- [Renderphase](https://toolboxjs.com/grid/api/plugin-development/types/renderphase.md)
- [Resizecontroller](https://toolboxjs.com/grid/api/plugin-development/interfaces/resizecontroller.md)
- [Scrollmapping](https://toolboxjs.com/grid/api/plugin-development/interfaces/scrollmapping.md)
- [Tovirtualscrolltop](https://toolboxjs.com/grid/api/plugin-development/functions/tovirtualscrolltop.md)
- [Virtualstate](https://toolboxjs.com/grid/api/plugin-development/interfaces/virtualstate.md)

### Framework Adapters

- [Datagridelement Adapters](https://toolboxjs.com/grid/api/framework-adapters/classes/datagridelement-adapters.md)
- [Externalmounteditordetail](https://toolboxjs.com/grid/api/framework-adapters/interfaces/externalmounteditordetail.md)
- [Externalmountviewdetail](https://toolboxjs.com/grid/api/framework-adapters/interfaces/externalmountviewdetail.md)
- [Frameworkadapter](https://toolboxjs.com/grid/api/framework-adapters/interfaces/frameworkadapter.md)

### Angular Adapter

- [Angularcolumngroupdefinition](https://toolboxjs.com/grid/angular/api/types/angularcolumngroupdefinition.md)
- [Angulargroupingcolumnsconfig](https://toolboxjs.com/grid/angular/api/types/angulargroupingcolumnsconfig.md)
- [Angulargroupingrowsconfig](https://toolboxjs.com/grid/angular/api/types/angulargroupingrowsconfig.md)
- [Angularpanelrender](https://toolboxjs.com/grid/angular/api/types/angularpanelrender.md)
- [Angularpanelslot](https://toolboxjs.com/grid/angular/api/types/angularpanelslot.md)
- [Angularpinnedrowsconfig](https://toolboxjs.com/grid/angular/api/types/angularpinnedrowsconfig.md)
- [Angularpinnedrowslot](https://toolboxjs.com/grid/angular/api/types/angularpinnedrowslot.md)
- [Angularzonedpanelrender](https://toolboxjs.com/grid/angular/api/types/angularzonedpanelrender.md)
- [Applycolumndefaults](https://toolboxjs.com/grid/angular/api/utilities/applycolumndefaults.md)
- [Basefilterpanel](https://toolboxjs.com/grid/angular/api/utilities/basefilterpanel.md)
- [Basegrideditor](https://toolboxjs.com/grid/angular/api/utilities/basegrideditor.md)
- [Basegrideditorcva](https://toolboxjs.com/grid/angular/api/utilities/basegrideditorcva.md)
- [Baseoverlayeditor](https://toolboxjs.com/grid/angular/api/utilities/baseoverlayeditor.md)
- [Cellcommitevent](https://toolboxjs.com/grid/angular/api/types/cellcommitevent.md)
- [Celleditor](https://toolboxjs.com/grid/angular/api/types/celleditor.md)
- [Cellrenderer](https://toolboxjs.com/grid/angular/api/types/cellrenderer.md)
- [Columnconfig](https://toolboxjs.com/grid/angular/api/types/columnconfig.md)
- [Columngroupdefinition](https://toolboxjs.com/grid/angular/api/types/columngroupdefinition.md)
- [Columnshorthand](https://toolboxjs.com/grid/angular/api/types/columnshorthand.md)
- [Createpluginfromfeature](https://toolboxjs.com/grid/angular/api/utilities/createpluginfromfeature.md)
- [Editormounthook](https://toolboxjs.com/grid/angular/api/types/editormounthook.md)
- [Exportmethods](https://toolboxjs.com/grid/angular/api/features/exportmethods.md)
- [Featurename](https://toolboxjs.com/grid/angular/api/types/featurename.md)
- [Filterconfig](https://toolboxjs.com/grid/angular/api/types/filterconfig.md)
- [Filteringmethods](https://toolboxjs.com/grid/angular/api/features/filteringmethods.md)
- [Filterpanel](https://toolboxjs.com/grid/angular/api/types/filterpanel.md)
- [Formarraycontext](https://toolboxjs.com/grid/angular/api/types/formarraycontext.md)
- [Getdetailtemplate](https://toolboxjs.com/grid/angular/api/utilities/getdetailtemplate.md)
- [Getfeaturefactory](https://toolboxjs.com/grid/angular/api/utilities/getfeaturefactory.md)
- [Getregisteredfeatures](https://toolboxjs.com/grid/angular/api/utilities/getregisteredfeatures.md)
- [Getresponsivecardtemplate](https://toolboxjs.com/grid/angular/api/utilities/getresponsivecardtemplate.md)
- [Grid](https://toolboxjs.com/grid/angular/api/directives/grid.md)
- [Gridadapter](https://toolboxjs.com/grid/angular/api/adapters/gridadapter.md)
- [Gridcellcontext](https://toolboxjs.com/grid/angular/api/types/gridcellcontext.md)
- [Gridclipboarddirective](https://toolboxjs.com/grid/angular/api/directives/gridclipboarddirective.md)
- [Gridcolumneditor](https://toolboxjs.com/grid/angular/api/utilities/gridcolumneditor.md)
- [Gridcolumnview](https://toolboxjs.com/grid/angular/api/directives/gridcolumnview.md)
- [Gridcolumnvirtualizationdirective](https://toolboxjs.com/grid/angular/api/directives/gridcolumnvirtualizationdirective.md)
- [Gridconfig](https://toolboxjs.com/grid/angular/api/types/gridconfig.md)
- [Gridcontextmenudirective](https://toolboxjs.com/grid/angular/api/directives/gridcontextmenudirective.md)
- [Griddetailcontext](https://toolboxjs.com/grid/angular/api/types/griddetailcontext.md)
- [Griddetailview](https://toolboxjs.com/grid/angular/api/directives/griddetailview.md)
- [Grideditingdirective](https://toolboxjs.com/grid/angular/api/directives/grideditingdirective.md)
- [Grideditorcontext](https://toolboxjs.com/grid/angular/api/types/grideditorcontext.md)
- [Gridexportdirective](https://toolboxjs.com/grid/angular/api/directives/gridexportdirective.md)
- [Gridfilteringdirective](https://toolboxjs.com/grid/angular/api/directives/gridfilteringdirective.md)
- [Gridformarray](https://toolboxjs.com/grid/angular/api/utilities/gridformarray.md)
- [Gridgroupingcolumnsdirective](https://toolboxjs.com/grid/angular/api/directives/gridgroupingcolumnsdirective.md)
- [Gridgroupingrowsdirective](https://toolboxjs.com/grid/angular/api/directives/gridgroupingrowsdirective.md)
- [Gridheadercontent](https://toolboxjs.com/grid/angular/api/directives/gridheadercontent.md)
- [Gridheadercontentcontext](https://toolboxjs.com/grid/angular/api/types/gridheadercontentcontext.md)
- [Gridiconregistry](https://toolboxjs.com/grid/angular/api/utilities/gridiconregistry.md)
- [Gridlazyform](https://toolboxjs.com/grid/angular/api/utilities/gridlazyform.md)
- [Gridmasterdetaildirective](https://toolboxjs.com/grid/angular/api/directives/gridmasterdetaildirective.md)
- [Gridmultisortdirective](https://toolboxjs.com/grid/angular/api/directives/gridmultisortdirective.md)
- [Gridpinnedcolumnsdirective](https://toolboxjs.com/grid/angular/api/directives/gridpinnedcolumnsdirective.md)
- [Gridpinnedrowsdirective](https://toolboxjs.com/grid/angular/api/directives/gridpinnedrowsdirective.md)
- [Gridpivotdirective](https://toolboxjs.com/grid/angular/api/directives/gridpivotdirective.md)
- [Gridprintdirective](https://toolboxjs.com/grid/angular/api/directives/gridprintdirective.md)
- [Gridreordercolumnsdirective](https://toolboxjs.com/grid/angular/api/directives/gridreordercolumnsdirective.md)
- [Gridreorderrowsdirective](https://toolboxjs.com/grid/angular/api/directives/gridreorderrowsdirective.md)
- [Gridresponsivecard](https://toolboxjs.com/grid/angular/api/directives/gridresponsivecard.md)
- [Gridresponsivecardcontext](https://toolboxjs.com/grid/angular/api/types/gridresponsivecardcontext.md)
- [Gridresponsivedirective](https://toolboxjs.com/grid/angular/api/directives/gridresponsivedirective.md)
- [Gridrowdragdropdirective](https://toolboxjs.com/grid/angular/api/directives/gridrowdragdropdirective.md)
- [Gridselectiondirective](https://toolboxjs.com/grid/angular/api/directives/gridselectiondirective.md)
- [Gridserversidedirective](https://toolboxjs.com/grid/angular/api/directives/gridserversidedirective.md)
- [Gridstickyrowsdirective](https://toolboxjs.com/grid/angular/api/directives/gridstickyrowsdirective.md)
- [Gridtoolbarcontent](https://toolboxjs.com/grid/angular/api/directives/gridtoolbarcontent.md)
- [Gridtoolbarcontentcontext](https://toolboxjs.com/grid/angular/api/types/gridtoolbarcontentcontext.md)
- [Gridtoolpanel](https://toolboxjs.com/grid/angular/api/directives/gridtoolpanel.md)
- [Gridtoolpanelcontext](https://toolboxjs.com/grid/angular/api/types/gridtoolpanelcontext.md)
- [Gridtooltipdirective](https://toolboxjs.com/grid/angular/api/directives/gridtooltipdirective.md)
- [Gridtreedirective](https://toolboxjs.com/grid/angular/api/directives/gridtreedirective.md)
- [Gridtyperegistry](https://toolboxjs.com/grid/angular/api/utilities/gridtyperegistry.md)
- [Gridundoredodirective](https://toolboxjs.com/grid/angular/api/directives/gridundoredodirective.md)
- [Gridvisibilitydirective](https://toolboxjs.com/grid/angular/api/directives/gridvisibilitydirective.md)
- [Groupingcolumnsconfig](https://toolboxjs.com/grid/angular/api/types/groupingcolumnsconfig.md)
- [Groupingrowsconfig](https://toolboxjs.com/grid/angular/api/types/groupingrowsconfig.md)
- [Hascolumnshorthands](https://toolboxjs.com/grid/angular/api/utilities/hascolumnshorthands.md)
- [Injectgrid](https://toolboxjs.com/grid/angular/api/utilities/injectgrid.md)
- [Injectgridexport](https://toolboxjs.com/grid/angular/api/features/injectgridexport.md)
- [Injectgridfiltering](https://toolboxjs.com/grid/angular/api/features/injectgridfiltering.md)
- [Injectgridprint](https://toolboxjs.com/grid/angular/api/features/injectgridprint.md)
- [Injectgridreturn](https://toolboxjs.com/grid/angular/api/types/injectgridreturn.md)
- [Injectgridselection](https://toolboxjs.com/grid/angular/api/features/injectgridselection.md)
- [Injectgridundoredo](https://toolboxjs.com/grid/angular/api/features/injectgridundoredo.md)
- [Iscomponentclass](https://toolboxjs.com/grid/angular/api/utilities/iscomponentclass.md)
- [Isfeatureregistered](https://toolboxjs.com/grid/angular/api/utilities/isfeatureregistered.md)
- [Lazyformfactory](https://toolboxjs.com/grid/angular/api/types/lazyformfactory.md)
- [Masterdetailconfig](https://toolboxjs.com/grid/angular/api/types/masterdetailconfig.md)
- [Normalizecolumns](https://toolboxjs.com/grid/angular/api/utilities/normalizecolumns.md)
- [Overlayposition](https://toolboxjs.com/grid/angular/api/types/overlayposition.md)
- [Panelrender](https://toolboxjs.com/grid/angular/api/types/panelrender.md)
- [Panelslot](https://toolboxjs.com/grid/angular/api/types/panelslot.md)
- [Parsecolumnshorthand](https://toolboxjs.com/grid/angular/api/utilities/parsecolumnshorthand.md)
- [Pinnedrowsconfig](https://toolboxjs.com/grid/angular/api/types/pinnedrowsconfig.md)
- [Pinnedrowslot](https://toolboxjs.com/grid/angular/api/types/pinnedrowslot.md)
- [Pluginfactory](https://toolboxjs.com/grid/angular/api/types/pluginfactory.md)
- [Printmethods](https://toolboxjs.com/grid/angular/api/features/printmethods.md)
- [Providegrid](https://toolboxjs.com/grid/angular/api/utilities/providegrid.md)
- [Providegridicons](https://toolboxjs.com/grid/angular/api/utilities/providegridicons.md)
- [Providegridoptions](https://toolboxjs.com/grid/angular/api/types/providegridoptions.md)
- [Providegridtypedefaults](https://toolboxjs.com/grid/angular/api/utilities/providegridtypedefaults.md)
- [Registerfeature](https://toolboxjs.com/grid/angular/api/utilities/registerfeature.md)
- [Responsivepluginconfig](https://toolboxjs.com/grid/angular/api/types/responsivepluginconfig.md)
- [Rowcommitevent](https://toolboxjs.com/grid/angular/api/types/rowcommitevent.md)
- [Rowformchangeevent](https://toolboxjs.com/grid/angular/api/types/rowformchangeevent.md)
- [Selectionmethods](https://toolboxjs.com/grid/angular/api/features/selectionmethods.md)
- [Tbweditor](https://toolboxjs.com/grid/angular/api/utilities/tbweditor.md)
- [Tbwgridcolumn](https://toolboxjs.com/grid/angular/api/directives/tbwgridcolumn.md)
- [Tbwgridheader](https://toolboxjs.com/grid/angular/api/directives/tbwgridheader.md)
- [Tbwgridtoolbuttons](https://toolboxjs.com/grid/angular/api/directives/tbwgridtoolbuttons.md)
- [Tbwrenderer](https://toolboxjs.com/grid/angular/api/directives/tbwrenderer.md)
- [Typedefault](https://toolboxjs.com/grid/angular/api/types/typedefault.md)
- [Typedefaultregistration](https://toolboxjs.com/grid/angular/api/types/typedefaultregistration.md)
- [Undoredomethods](https://toolboxjs.com/grid/angular/api/features/undoredomethods.md)
- [Zonedpanelrender](https://toolboxjs.com/grid/angular/api/types/zonedpanelrender.md)