# DataGridElement (Plugin API)

Internal API for plugin developers. Members marked with `@internal Plugin API`
or using the `_underscore` prefix convention.

See the [public API documentation](/grid/api/core/classes/datagridelement.md) for consumer-facing members.

| Prefix | Meaning |
| ------ | ------- |
| _(none)_ | Public API |
| `_` | Protected/plugin-accessible |
| `__` | Deeply internal (not documented) |

## Events

| Event | Description | Triggered By |
| ----- | ----------- | ------------ |
| `cell-activate` | Unified activation event (cancelable) - fires FIRST | `_dispatchCellClick()` |
| `cell-click` | Emitted after plugins process the click, with full cell context | `_dispatchCellClick()` |
| `row-click` | Emitted after plugins process the click, with full row context | `_dispatchRowClick()` |

## Properties

| Property | Type | Description |
| -------- | ---- | ----------- |
| `_rows` | <code>T[]</code> |  |
| `_headerRowEl` | <code>HTMLElement</code> |  |
| `_bodyEl` | <code>HTMLElement</code> |  |
| `_rowPool` | <code><a href="/grid/api/plugin-development/interfaces/rowelementinternal/">RowElementInternal</a>[]</code> |  |
| `_resizeController` | <code><a href="/grid/api/plugin-development/interfaces/resizecontroller/">ResizeController</a></code> |  |
| `_focusRow` | <code>number</code> |  |
| `_focusCol` | <code>number</code> |  |
| `_restoreFocusAfterRender` | <code>boolean</code> | Flag to restore focus styling after next render. |
| `_sortState` | <code>object &#124; unknown</code> |  |
| `_gridTemplate` | <code>string</code> |  |

## Event Dispatching
 Plugin API - called by event-delegation.ts

### _dispatchCellMouseDown()

Dispatch cell mouse events for drag operations.
Returns true if any plugin started a drag.

```ts
_dispatchCellMouseDown(event: CellMouseEvent): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `event` | <code><a href="/grid/api/plugin-development/interfaces/cellmouseevent/">CellMouseEvent</a></code> |  |

***

### _dispatchCellMouseMove()

Dispatch cell mouse move during drag.

```ts
_dispatchCellMouseMove(event: CellMouseEvent): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `event` | <code><a href="/grid/api/plugin-development/interfaces/cellmouseevent/">CellMouseEvent</a></code> |  |

***

### _dispatchCellMouseUp()

Dispatch cell mouse up to end drag.

```ts
_dispatchCellMouseUp(event: CellMouseEvent): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `event` | <code><a href="/grid/api/plugin-development/interfaces/cellmouseevent/">CellMouseEvent</a></code> |  |

***

## Plugin Hooks
 Plugin API - called by rows.ts

### _afterCellRender()

Call afterCellRender hook on all plugins.
This is called by rows.ts for each cell after it's rendered,
allowing plugins to modify cells during render rather than
requiring expensive post-render DOM queries.

```ts
_afterCellRender(context: AfterCellRenderContext<T>): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `context` | <code><a href="/grid/api/plugin-development/interfaces/aftercellrendercontext/">AfterCellRenderContext</a>&lt;T&gt;</code> |  |

***

### _hasAfterCellRenderHook()

Check if any plugin has registered an afterCellRender hook.
Used to skip the hook call entirely for performance when no plugins need it.

```ts
_hasAfterCellRenderHook(): boolean
```

***

### _afterRowRender()

Call afterRowRender hook on all plugins that have registered for it.
Called by rows.ts after each row is completely rendered.

```ts
_afterRowRender(context: AfterRowRenderContext<T>): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `context` | <code><a href="/grid/api/plugin-development/interfaces/afterrowrendercontext/">AfterRowRenderContext</a>&lt;T&gt;</code> | Context containing row data, index, and DOM element |

***

### _hasAfterRowRenderHook()

Check if any plugin has registered an afterRowRender hook.
Used to skip the hook call entirely for performance when no plugins need it.

```ts
_hasAfterRowRenderHook(): boolean
```

***

## Accessors

### _pluginManager

Exposes plugin manager for event bus operations (subscribe/unsubscribe/emit).
Plugins access this via `this.grid._pluginManager` in `BaseGridPlugin.on/off/emitPluginEvent`.

```ts
readonly _pluginManager: PluginManager | undefined
```

***

### _columns

```ts
_columns: ColumnInternal<T>[]
```

***

### _visibleColumns

Visible columns only (excludes hidden). Use for rendering.

```ts
readonly _visibleColumns: ColumnInternal<T>[]
```

***

### _virtualization

```ts
_virtualization: VirtualState
```

***

### _sourceConfig

Plugin API - the original, unmerged source config as supplied via
the `gridConfig` property. Plugins read this (not gridConfig, which
returns the merged result) to distinguish caller-supplied values from
plugin/API-contributed ones.

```ts
readonly _sourceConfig: GridConfig<T> | undefined
```

***

### _schedulerIsConnected

Whether the grid is fully connected (scheduler guard).

```ts
readonly _schedulerIsConnected: boolean
```

***

### _hostElement

The grid's host HTMLElement. Use instead of casting `grid as unknown as HTMLElement`.

```ts
readonly _hostElement: HTMLElement
```

***

### _renderRoot

The grid's render root element for DOM queries.

```ts
readonly _renderRoot: HTMLElement
```

***

### _accordionIcons

Get accordion expand/collapse icons from effective config.

```ts
readonly _accordionIcons: object
```

***

### _shellState

Shell state for config manager shell merging.

```ts
readonly _shellState: ShellState
```

***

## Methods

### _invalidateVisibleColumnsCache()

Clear the cached _visibleColumns so the next access recomputes from _columns.
Called by ConfigManager when it mutates effectiveConfig.columns directly
(bypassing the _columns setter which normally handles invalidation).

```ts
_invalidateVisibleColumnsCache(): void
```

***

### _registerLightDomHandler()

Plugin API - register a generic light-DOM mutation handler. The
observer is tag-agnostic core infrastructure; plugins (e.g. ShellPlugin)
declare which tags they watch and own the parsing logic.

```ts
_registerLightDomHandler(tagName: string, callback: () => void): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `tagName` | <code>string</code> |  |
| `callback` | <code>() =&gt; void</code> |  |

***

### _unregisterLightDomHandler()

Plugin API - unregister a light-DOM handler.

```ts
_unregisterLightDomHandler(tagName: string): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `tagName` | <code>string</code> |  |

***

### _requestConfigMerge()

Plugin API - re-merge config sources into `effectiveConfig`.
Plugins call this after re-parsing light DOM so the `processConfig` hook
folds the new values in.

```ts
_requestConfigMerge(): void
```

***

### _getToolPanelRendererFactory()

Plugin API - build a renderer factory from registered framework
adapters. Generic adapter capability (not shell-specific).

```ts
_getToolPanelRendererFactory(): (element: HTMLElement) => (container: HTMLElement) => void | () => void | undefined | undefined
```

***

### _emitDataChange()

```ts
_emitDataChange(): void
```

***

### _rebuildRowIdMap()

Rebuild the row ID map for O(1) lookups.
Called when rows array changes.

```ts
_rebuildRowIdMap(): void
```

***

### _renderVisibleRows()

```ts
_renderVisibleRows(start: number, end: number, epoch: number): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `start` | <code>number</code> |  |
| `end` | <code>number</code> |  |
| `epoch` | <code>number</code> |  |

***

### _updateAriaCounts()

Updates ARIA row/col counts. Delegates to aria.ts module.

```ts
_updateAriaCounts(rowCount: number, colCount: number): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `rowCount` | <code>number</code> |  |
| `colCount` | <code>number</code> |  |

***

### _requestSchedulerPhase()

Request a render at the given phase through the scheduler.

```ts
_requestSchedulerPhase(phase: RenderPhase, source: string): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `phase` | <code><a href="/grid/api/plugin-development/types/renderphase/">RenderPhase</a></code> |  |
| `source` | <code>string</code> |  |

***

### _getPluginRowHeight()

Plugin-specific row height override.

```ts
_getPluginRowHeight(row: T, index: number): number | undefined
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `row` | <code>T</code> |  |
| `index` | <code>number</code> |  |

***

### _adjustPluginVirtualStart()

Let plugins adjust the virtual start index backwards.

```ts
_adjustPluginVirtualStart(start: number, scrollTop: number, rowHeight: number): number | undefined
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `start` | <code>number</code> |  |
| `scrollTop` | <code>number</code> |  |
| `rowHeight` | <code>number</code> |  |

***

### _afterPluginRender()

Run plugin afterRender hooks.

```ts
_afterPluginRender(): void
```

***

### _emitPluginEvent()

Emit a plugin event through the plugin manager.

```ts
_emitPluginEvent(event: string, detail: unknown): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `event` | <code>string</code> |  |
| `detail` | <code>unknown</code> |  |

***

### _schedulerMergeConfig()

Merge effective config (FULL/COLUMNS phase).

```ts
_schedulerMergeConfig(): void
```

***

### _schedulerProcessColumns()

Process columns through plugins (COLUMNS phase).

```ts
_schedulerProcessColumns(): void
```

***

### _schedulerProcessRows()

Rebuild row model through plugins (ROWS phase).

```ts
_schedulerProcessRows(): void
```

***

### _schedulerRenderHeader()

Render header DOM (HEADER phase).

```ts
_schedulerRenderHeader(): void
```

***

### _schedulerUpdateTemplate()

Update CSS grid template (COLUMNS phase).

```ts
_schedulerUpdateTemplate(): void
```

***

### _schedulerAfterRender()

Run afterRender hooks and post-render bookkeeping (STYLE phase).

```ts
_schedulerAfterRender(): void
```

***

### _emit()

Emit a custom event from the grid.

```ts
_emit(eventName: string, detail: unknown): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `eventName` | <code>string</code> |  |
| `detail` | <code>unknown</code> |  |

***

### _clearRowPool()

Clear the row pool and body element.

```ts
_clearRowPool(): void
```

***

### _setup()

Run grid setup (DOM rebuild).

```ts
_setup(): void
```

***

### _applyAnimationConfig()

Apply animation configuration to host element.

```ts
_applyAnimationConfig(gridConfig: GridConfig<T>): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `gridConfig` | <code><a href="/grid/api/core/interfaces/gridconfig/">GridConfig</a>&lt;T&gt;</code> |  |

***

### _dispatchCellClick()

Dispatch a cell click event to the plugin system, then emit a public event.
Plugins get first chance to handle the event. After plugins process it,
a `cell-click` CustomEvent is dispatched for external listeners.

```ts
_dispatchCellClick(event: MouseEvent, rowIndex: number, colIndex: number, cellEl: HTMLElement): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `event` | <code>MouseEvent</code> |  |
| `rowIndex` | <code>number</code> |  |
| `colIndex` | <code>number</code> |  |
| `cellEl` | <code>HTMLElement</code> |  |

#### Returns

`boolean` - `true` if any plugin handled (consumed) the event, or if consumer canceled

#### Events

| Event | Description |
| ----- | ----------- |
| `cell-activate` | Unified activation event (cancelable) - fires FIRST |
| `cell-click` | Emitted after plugins process the click, with full cell context |

***

### _dispatchRowClick()

Dispatch a row click event to the plugin system, then emit a public event.
Plugins get first chance to handle the event. After plugins process it,
a `row-click` CustomEvent is dispatched for external listeners.

```ts
_dispatchRowClick(event: MouseEvent, rowIndex: number, row: any, rowEl: HTMLElement): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `event` | <code>MouseEvent</code> |  |
| `rowIndex` | <code>number</code> |  |
| `row` | <code>any</code> |  |
| `rowEl` | <code>HTMLElement</code> |  |

#### Returns

`boolean` - `true` if any plugin handled (consumed) the event

#### Events

| Event | Description |
| ----- | ----------- |
| `row-click` | Emitted after plugins process the click, with full row context |

***

### _dispatchHeaderClick()

Dispatch a header click event to the plugin system.
Returns true if any plugin handled the event.

```ts
_dispatchHeaderClick(event: MouseEvent | KeyboardEvent, col: ColumnConfig, headerEl: HTMLElement): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `event` | <code>MouseEvent &#124; KeyboardEvent</code> |  |
| `col` | <code><a href="/grid/api/core/interfaces/columnconfig/">ColumnConfig</a></code> |  |
| `headerEl` | <code>HTMLElement</code> |  |

***

### _dispatchKeyDown()

Dispatch a keyboard event to the plugin system.
Returns true if any plugin handled the event.

```ts
_dispatchKeyDown(event: KeyboardEvent): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `event` | <code>KeyboardEvent</code> |  |

***

### _getHorizontalScrollOffsets()

Get horizontal scroll boundary offsets from plugins.
Used by keyboard navigation to ensure focused cells are fully visible
when plugins like pinned columns obscure part of the scroll area.

```ts
_getHorizontalScrollOffsets(rowEl: HTMLElement, focusedCell: HTMLElement): object
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `rowEl` | <code>HTMLElement</code> |  |
| `focusedCell` | <code>HTMLElement</code> |  |

***

### _getRowEntry()

Get a row and its current index by ID.
Used internally by plugins to resolve a row's current position in `_rows`
after sorting, filtering, or rows replacement.

```ts
_getRowEntry(id: string): object | undefined
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `id` | <code>string</code> |  |

***

### refreshShellHeader()

Re-parse light DOM shell elements and refresh shell header.
Call this after dynamically modifying &lt;tbw-grid-header&gt; children.

Multiple calls are batched via microtask to avoid redundant DOM rebuilds
when registering multiple tool panels in sequence.

 Plugin API

```ts
refreshShellHeader(): void
```

***