EditingPlugin

Editing Plugin for tbw-grid

Enables inline cell editing in the grid. 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:

• Smaller bundle — Apps that only display data don’t pay for editing code
• Clear intent — Explicit plugin registration makes editing capability obvious
• Runtime validation — Using editable: true without the plugin throws a helpful error

Installation

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

Edit Triggers

Configure how editing is triggered with the editOn option:

Value	Behavior
'click'	Single click enters edit mode (default)
'dblclick'	Double-click enters edit mode

Keyboard Shortcuts

Key	Action
Enter	Commit edit and move down
Tab	Commit edit and move right
Escape	Cancel edit, restore original value
Arrow Keys	Navigate between cells (when not editing)

Configuration Options

Option	Type	Description
mode?	row | grid	Editing mode that determines how many rows are editable at once.
dirtyTracking?	boolean	Enable per-row dirty tracking against deep-cloned baselines.
editOn?	false | click | dblclick | manual	Controls when editing is triggered (only applies to mode: 'row'). - ‘click’: Edit on single click (default) - ‘dblclick’: Edit on double click - ‘manual’: Only via programmatic API (beginEdit) - false: Disable editing entirely
onBeforeEditClose?	(event: MouseEvent | KeyboardEvent) => boolean	Callback invoked before a row edit session closes.
focusTrap?	boolean	When true, prevents focus from leaving the grid (or its registered external focus containers) while a row is in edit mode.

Examples

Basic editing with double-click trigger

grid.gridConfig = {
  columns: [
    { field: 'name', editable: true },
    { field: 'price', type: 'number', editable: true },
    { field: 'active', type: 'boolean', editable: true },
  ],
  plugins: [new EditingPlugin({ editOn: 'dblclick' })],
};

grid.on('cell-commit', ({ field, oldValue, newValue }) => {
  console.log(`${field}: ${oldValue} → ${newValue}`);
});

Custom editor function

columns: [
  {
    field: 'status',
    editable: true,
    editor: (ctx) => {
      const select = document.createElement('select');
      ['pending', 'active', 'completed'].forEach(opt => {
        const option = document.createElement('option');
        option.value = opt;
        option.textContent = opt;
        option.selected = ctx.value === opt;
        select.appendChild(option);
      });
      select.addEventListener('change', () => ctx.commit(select.value));
      return select;
    },
  },
]

See Also

• EditingConfig for configuration options
• EditorContext for custom editor context
• EditingConfig for interactive examples in the docs site

Extends BaseGridPlugin

Inherited methods like attach(), detach(), afterRender(), etc. are documented in the base class.

Events

Event	Description	Triggered By
changed-rows-reset	Emitted when tracking is reset (unless silent)	resetChangedRows()
cell-commit	Emitted when the cell value is committed (on blur or Enter)	beginCellEdit(), beginBulkEdit()
row-commit	Emitted after the row edit is committed	beginBulkEdit(), commitActiveRowEdit()

Accessors

changedRows

Get all rows that have been modified. Uses ID-based lookup for stability when rows are reordered.

readonly changedRows: T[]

---

changedRowIds

Get IDs of all modified rows.

readonly changedRowIds: string[]

---

activeEditRow

Get the currently active edit row index, or -1 if not editing.

readonly activeEditRow: number

---

activeEditCol

Get the currently active edit column index, or -1 if not editing.

readonly activeEditCol: number

---

dirty

Whether any row in the grid is dirty.

readonly dirty: boolean

---

pristine

Whether all rows are pristine.

readonly pristine: boolean

---

dirtyRowIds

Get IDs of all dirty rows.

readonly dirtyRowIds: string[]

---

Methods

isRowEditing()

Check if a specific row is currently being edited.

isRowEditing(rowIndex: number): boolean

Parameters

Name	Type	Description
rowIndex	number

---

isCellEditing()

Check if a specific cell is currently being edited.

isCellEditing(rowIndex: number, colIndex: number): boolean

Parameters

Name	Type	Description
rowIndex	number
colIndex	number

---

isRowChanged()

Check if a specific row has been modified.

isRowChanged(rowIndex: number): boolean

Parameters

Name	Type	Description
rowIndex	number	Row index to check (will be converted to ID internally)

---

isRowChangedById()

Check if a row with the given ID has been modified.

isRowChangedById(rowId: string): boolean

Parameters

Name	Type	Description
rowId	string	Row ID to check

---

isDirty()

Check if a row differs from its baseline. Requires dirtyTracking: true.

isDirty(rowId: string): boolean

Parameters

Name	Type	Description
rowId	string

---

isPristine()

Inverse of isDirty.

isPristine(rowId: string): boolean

Parameters

Name	Type	Description
rowId	string

---

markAsPristine()

Re-snapshot baseline from current data (call after a successful save).

markAsPristine(rowId: string): void

Parameters

Name	Type	Description
rowId	string

---

markAsNew()

Mark a row as new (auto-called by insertRow() when dirty tracking is on).

markAsNew(rowId: string): void

Parameters

Name	Type	Description
rowId	string

---

markAsDirty()

Mark a row as dirty after an external mutation that bypassed the editing pipeline.

markAsDirty(rowId: string): void

Parameters

Name	Type	Description
rowId	string

---

markAllPristine()

Mark all tracked rows as pristine (call after a batch save).

markAllPristine(): void

---

getOriginalRow()

Get a deep clone of the original (baseline) row data. Returns undefined for new rows.

getOriginalRow(rowId: string): T | undefined

Parameters

Name	Type	Description
rowId	string

---

hasBaseline()

Lightweight check for whether a baseline exists (no cloning).

hasBaseline(rowId: string): boolean

Parameters

Name	Type	Description
rowId	string

---

getDirtyRows()

Get all dirty rows with their original and current data.

getDirtyRows(): DirtyRowEntry<T>[]

---

revertRow()

Revert a row to its baseline values (mutates the current row in-place). Triggers a re-render.

revertRow(rowId: string): void

Parameters

Name	Type	Description
rowId	string	Row ID (from getRowId)

---

revertAll()

Revert all dirty rows to their baseline values and re-render.

revertAll(): void

---

setInvalid()

Mark a cell as invalid with an optional validation message. Invalid cells are marked with a data-invalid attribute for styling.

setInvalid(rowId: string, field: string, message: string): void

Parameters

Name	Type	Description
rowId	string	The row ID (from getRowId)
field	string	The field name
message	string	Optional validation message (for tooltips or display)

Example

// In cell-commit handler:
grid.on('cell-commit', (detail, e) => {
  if (detail.field === 'email' && !isValidEmail(detail.value)) {
    detail.setInvalid('Invalid email format');
  }
});

// Or programmatically:
editingPlugin.setInvalid('row-123', 'email', 'Invalid email format');

---

clearInvalid()

Clear the invalid state for a specific cell.

clearInvalid(rowId: string, field: string): void

Parameters

Name	Type	Description
rowId	string
field	string

---

clearRowInvalid()

Clear all invalid cells for a specific row.

clearRowInvalid(rowId: string): void

Parameters

Name	Type	Description
rowId	string

---

clearAllInvalid()

Clear all invalid cell states across all rows.

clearAllInvalid(): void

---

isCellInvalid()

Check if a specific cell is marked as invalid.

isCellInvalid(rowId: string, field: string): boolean

Parameters

Name	Type	Description
rowId	string
field	string

---

getInvalidMessage()

Get the validation message for an invalid cell.

getInvalidMessage(rowId: string, field: string): string | undefined

Parameters

Name	Type	Description
rowId	string
field	string

---

hasInvalidCells()

Check if a row has any invalid cells.

hasInvalidCells(rowId: string): boolean

Parameters

Name	Type	Description
rowId	string

---

getInvalidFields()

Get all invalid fields for a row.

getInvalidFields(rowId: string): Map<string, string>

Parameters

Name	Type	Description
rowId	string

---

resetChangedRows()

Reset all change tracking.

resetChangedRows(silent: boolean): void

Parameters

Name	Type	Description
silent	boolean	If true, suppresses the changed-rows-reset event

Events

Event	Description
changed-rows-reset	Emitted when tracking is reset (unless silent)

---

beginCellEdit()

Programmatically begin editing a cell.

beginCellEdit(rowIndex: number, field: string): void

Parameters

Name	Type	Description
rowIndex	number	Index of the row to edit
field	string	Field name of the column to edit

Events

Event	Description
cell-commit	Emitted when the cell value is committed (on blur or Enter)

---

beginBulkEdit()

Programmatically begin editing all editable cells in a row.

beginBulkEdit(rowIndex: number): void

Parameters

Name	Type	Description
rowIndex	number	Index of the row to edit

Events

Event	Description
cell-commit	Emitted for each cell value that is committed
row-commit	Emitted when focus leaves the row

---

commitActiveRowEdit()

Commit the currently active row edit.

commitActiveRowEdit(): void

Events

Event	Description
row-commit	Emitted after the row edit is committed

---

cancelActiveRowEdit()

Cancel the currently active row edit.

cancelActiveRowEdit(): void

---