# TooltipPlugin

> _Since v1.28.0_

Tooltip Plugin for tbw-grid

Shows styled popover tooltips when header or cell text overflows its
container. Uses the Popover API with CSS anchor positioning for
consistent themed appearance across light and dark modes.

## Installation

```ts
import { TooltipPlugin } from '@toolbox-web/grid/plugins/tooltip';
```

## [Configuration Options](/grid/plugins/tooltip/interfaces/tooltipconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `header?` | <code>boolean</code> | Enable automatic header tooltips when text overflows. Individual columns can override with `headerTooltip`. |
| `cell?` | <code>boolean</code> | Enable automatic cell tooltips when text overflows. Individual columns can override with `cellTooltip`. |

## Examples

### Default — auto-tooltip on overflow

```ts
grid.gridConfig = {
  plugins: [new TooltipPlugin()],
};
```

### Header-only tooltips

```ts
grid.gridConfig = {
  plugins: [new TooltipPlugin({ cell: false })],
};
```

### Per-column overrides

```ts
grid.gridConfig = {
  columns: [
    { field: 'name', cellTooltip: (ctx) => `${ctx.row.first} ${ctx.row.last}` },
    { field: 'actions', cellTooltip: false },
    { field: 'revenue', headerTooltip: 'Total revenue in USD (before tax)' },
  ],
  plugins: [new TooltipPlugin()],
};
```

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

## Properties

| Property | Type | Description |
| -------- | ---- | ----------- |
| `name` | <code>tooltip</code> | Unique plugin identifier (derived from class name by default) |
| `styles` | <code>string</code> | CSS styles to inject via `document.adoptedStyleSheets` |
| `manifest` | <code><a href="/grid/api/plugin-development/interfaces/pluginmanifest/">PluginManifest</a>&lt;<a href="/grid/plugins/tooltip/interfaces/tooltipconfig/">TooltipConfig</a>&gt;</code> | Plugin manifest - declares owned properties, config rules, and hook priorities. |

### Property Details

#### manifest

Plugin manifest - declares owned properties, config rules, and hook priorities.

This is read by the configuration validator to:
- Validate that required plugins are loaded when their properties are used
- Execute configRules to detect invalid/conflicting settings
- Order hook execution based on priority

```typescript
static override readonly manifest: PluginManifest<MyConfig> = {
  ownedProperties: [
    { property: 'myProp', level: 'column', description: 'the "myProp" column property' },
  ],
  configRules: [
    { id: 'myPlugin/conflict', severity: 'warn', message: '...', check: (c) => c.a && c.b },
  ],
};
```

---

## Methods

### attach()

`override` — Called when the plugin is attached to a grid.
Override to set up event listeners, initialize state, etc.

```ts
attach(grid: GridElement): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `grid` | <code>GridElement</code> |  |

#### Example

```ts
attach(grid: GridElement): void {
  super.attach(grid);
  // Set up document-level listeners with auto-cleanup
  document.addEventListener('keydown', this.handleEscape, {
    signal: this.disconnectSignal
  });
}
```

***

### detach()

`override` — Called when the plugin is detached from a grid.
Override to clean up event listeners, timers, etc.

```ts
detach(): void
```

#### Example

```ts
detach(): void {
  // Clean up any state not handled by disconnectSignal
  this.selectedRows.clear();
  this.cache = null;
}
```

***

### afterRender()

`override` — Called after each render cycle completes.
Use this for DOM manipulation, adding event listeners to rendered elements,
or applying visual effects like selection highlights.

```ts
afterRender(): void
```

#### Example

```ts
afterRender(): void {
  // Apply selection styling to rendered rows
  const rows = this.gridElement?.querySelectorAll('.data-grid-row');
  rows?.forEach((row, i) => {
    row.classList.toggle('selected', this.selectedRows.has(i));
  });
}
```

***