PublicGrid

Since v0.1.1

Public API interface for DataGrid component.

Property Getters vs Setters:

Property getters return the EFFECTIVE (resolved) value after merging all config sources. This is the “current situation” - what consumers and plugins need to know.

Property setters accept input values which are merged into the effective config. Multiple sources can contribute (gridConfig, columns prop, light DOM, individual props).

For example:

• grid.fitMode returns the resolved fitMode (e.g., ‘stretch’ even if you set undefined)
• grid.columns returns the effective columns after merging
• grid.gridConfig returns the full effective config

Properties

Property	Type	Description
gridConfig?	GridConfig<T, ColumnFieldKey<T>>	Full config object. Setter merges with other inputs per precedence rules. Getter returns the effective (resolved) config.
columns?	ColumnConfig<T, ColumnFieldKey<T>>[]	Column definitions. Getter returns effective columns (after merging config, light DOM, inference).
rows?	T[]	Current row data (after plugin processing like grouping, filtering).
ready?	() => Promise<void>	Resolves once the component has finished initial work (layout, inference).
forceLayout?	() => Promise<void>	Force a layout / measurement pass (e.g. after container resize).
getConfig?	() => Promise<Readonly<GridConfig<T, ColumnFieldKey<T>>>>	Return effective resolved config (after inference & precedence).
toggleGroup?	(key: string) => Promise<void>	Toggle expansion state of a group row by its generated key.
registerStyles?	(id: string, css: string) => void	Register custom CSS styles to be injected into the grid. Use this to style custom cell renderers, editors, or detail panels.
unregisterStyles?	(id: string) => void	Remove previously registered custom styles.
getRegisteredStyles?	() => string[]	Get list of registered custom style IDs.
columnState?	GridColumnState	Read the current column state. Property-style accessor that mirrors PublicGrid.getColumnState. To restore state, use PublicGrid.applyColumnState.
sortModel?	{ field: string; direction: desc | asc } | unknown	Get the current sort state.
loading?	boolean	Whether the grid is currently in a loading state. When true, displays a loading overlay with spinner.
focusedCell?	{ rowIndex: number; colIndex: number; field: string } | unknown	The currently focused cell position, or null if no rows are loaded.

Property Details

columnState

const snapshot = grid.columnState;

---

sortModel

Get the current sort state.

Returns null when no sort is active.

const sort = grid.sortModel;
// { field: 'id', direction: 'desc' } | null

---

loading

Whether the grid is currently in a loading state. When true, displays a loading overlay with spinner.

Can also be set via the loading HTML attribute.

// Show loading overlay
grid.loading = true;
const data = await fetchData();
grid.rows = data;
grid.loading = false;

---

Methods

insertRow()

Insert a row at a visible index, bypassing the sort/filter pipeline. Auto-animates by default.

insertRow(index: number, row: T, animate: boolean): Promise<void>

Parameters

Name	Type	Description
index	number
row	T
animate	boolean

---

removeRow()

Remove a row at a visible index, bypassing the sort/filter pipeline. Auto-animates by default.

removeRow(index: number, animate: boolean): Promise<T | undefined>

Parameters

Name	Type	Description
index	number
animate	boolean

---

applyTransaction()

Apply a batch of add/update/remove mutations in a single render cycle.

applyTransaction(transaction: RowTransaction<T>, animate: boolean): Promise<TransactionResult<T>>

Parameters

Name	Type	Description
transaction	RowTransaction<T>
animate	boolean

---

applyTransactionAsync()

Batch-friendly version — merges rapid calls within a single animation frame.

applyTransactionAsync(transaction: RowTransaction<T>): Promise<TransactionResult<T>>

Parameters

Name	Type	Description
transaction	RowTransaction<T>

---

getPlugin()

Get a plugin instance by its class.

Prefer getPluginByName — it avoids importing the plugin class and returns the actual registered instance with full type narrowing.

getPlugin(PluginClass: (args: any[]) => P): P | undefined

Parameters

Name	Type	Description
PluginClass	(args: any[]) => P

Example

// Preferred: by name
const selection = grid.getPluginByName('selection');

// Alternative: by class
const selection = grid.getPlugin(SelectionPlugin);
if (selection) {
  selection.selectAll();
}

---

getPluginByName()

Get a plugin instance by its name.

When a plugin augments the PluginNameMap interface, the return type is narrowed automatically:

const editing = grid.getPluginByName('editing');
editing?.beginBulkEdit(0); // ✅ typed as EditingPlugin

For unknown names the return type falls back to GridPlugin | undefined.

getPluginByName(name: K): unknown | undefined

Parameters

Name	Type	Description
name	K

---

refreshShellHeader()

Re-render the shell header (title, column groups, toolbar). Call this after dynamically adding/removing tool panels or toolbar buttons.

refreshShellHeader(): void

---

registerToolPanel()

Register a custom tool panel in the sidebar.

registerToolPanel(panel: ToolPanelDefinition): void

Parameters

Name	Type	Description
panel	ToolPanelDefinition

Example

grid.registerToolPanel({
  id: 'analytics',
  title: 'Analytics',
  icon: '📊',
  render: (container) => {
    container.innerHTML = '<div>Charts here...</div>';
  }
});

---

unregisterToolPanel()

Unregister a previously registered tool panel.

unregisterToolPanel(panelId: string): void

Parameters

Name	Type	Description
panelId	string

---

openToolPanel()

Open the tool panel sidebar.

openToolPanel(panelId: string): void

Parameters

Name	Type	Description
panelId	string	Optional ID of the section to expand on open. Takes precedence
over shell.toolPanel.defaultOpen. Falls back to default behavior with a
warning if the ID is not registered.

---

closeToolPanel()

Close the tool panel sidebar.

closeToolPanel(): void

---

toggleToolPanel()

Toggle the tool panel sidebar open or closed.

toggleToolPanel(): void

---

toggleToolPanelSection()

Toggle an accordion section expanded or collapsed within the tool panel.

toggleToolPanelSection(sectionId: string): void

Parameters

Name	Type	Description
sectionId	string	The ID of the section to toggle

---

getColumnState()

Get the current column state including order, width, visibility, and sort. Use for persisting user preferences to localStorage or a backend.

getColumnState(): GridColumnState

Example

const state = grid.getColumnState();
localStorage.setItem('gridState', JSON.stringify(state));

---

applyColumnState()

Apply a previously saved column state, restoring column order, widths, visibility, sort, and any plugin-contributed state. Can be called before or after grid initialization — pre-init calls are deferred and applied during setup.

applyColumnState(state: GridColumnState | undefined): void

Parameters

Name	Type	Description
state	GridColumnState | undefined

Example

const saved = localStorage.getItem('gridState');
if (saved) grid.applyColumnState(JSON.parse(saved));

---

sort()

Sort by a column, toggle a column’s sort direction, or clear sorting.

• sort('id', 'desc') — apply sort with explicit direction
• sort('id') — toggle: none → asc → desc → none
• sort(null) — clear sort, restore original row order

sort(field: string | null, direction: "desc" | "asc"): void

Parameters

Name	Type	Description
field	string | unknown	Column field to sort by, or null to clear
direction	desc | asc	Explicit direction; omit to toggle

Example

grid.sort('id', 'desc');  // sort descending
grid.sort('price');       // toggle sort on price
grid.sort(null);          // clear sort

---

setRowLoading()

Set loading state for a specific row. Displays a small spinner indicator on the row.

Use when persisting row data or performing row-level async operations.

setRowLoading(rowId: string, loading: boolean): void

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier (from getRowId)
loading	boolean	Whether the row is loading

Example

// Show loading while saving row
grid.setRowLoading('emp-123', true);
await saveRow(row);
grid.setRowLoading('emp-123', false);

---

setCellLoading()

Set loading state for a specific cell. Displays a small spinner indicator on the cell.

Use when performing cell-level async operations (e.g., validation, lookup).

setCellLoading(rowId: string, field: string, loading: boolean): void

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier (from getRowId)
field	string	The column field
loading	boolean	Whether the cell is loading

Example

// Show loading while validating cell
grid.setCellLoading('emp-123', 'email', true);
const isValid = await validateEmail(email);
grid.setCellLoading('emp-123', 'email', false);

---

isRowLoading()

Check if a row is currently in loading state.

isRowLoading(rowId: string): boolean

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier

---

isCellLoading()

Check if a cell is currently in loading state.

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

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier
field	string	The column field

---

clearAllLoading()

Clear all row and cell loading states.

clearAllLoading(): void

---

registerExternalFocusContainer()

Register an external DOM element as a logical focus container of this grid.

Focus moving into a registered container is treated as if it stayed inside the grid: data-has-focus is preserved, click-outside commit is suppressed, and the editing focus trap (when enabled) won’t reclaim focus.

Typical use case: overlay panels (datepickers, dropdowns, autocompletes) that render at <body> level to escape grid overflow clipping.

registerExternalFocusContainer(el: Element): void

Parameters

Name	Type	Description
el	Element	The external element to register

Example

const overlay = document.createElement('div');
document.body.appendChild(overlay);

// Tell the grid this overlay is "part of" the grid
grid.registerExternalFocusContainer(overlay);

// Later, when overlay is removed
grid.unregisterExternalFocusContainer(overlay);

---

unregisterExternalFocusContainer()

Unregister a previously registered external focus container.

unregisterExternalFocusContainer(el: Element): void

Parameters

Name	Type	Description
el	Element	The element to unregister

---

containsFocus()

Check whether focus is logically inside this grid.

Returns true when document.activeElement (or the given node) is inside the grid’s own DOM or inside any element registered via registerExternalFocusContainer.

containsFocus(node: Node | null): boolean

Parameters

Name	Type	Description
node	Node | unknown	Optional node to test. Defaults to document.activeElement.

Example

if (grid.containsFocus()) {
  console.log('Grid or one of its overlays has focus');
}

---

focusCell()

Move focus to a specific cell.

focusCell(rowIndex: number, column: string | number): void

Parameters

Name	Type	Description
rowIndex	number	Row index (0-based, in the current processed row array)
column	string | number	Column index (0-based into visible columns) or field name

---

scrollToRow()

Scroll to make a row visible by its index.

scrollToRow(rowIndex: number, options: ScrollToRowOptions): void

Parameters

Name	Type	Description
rowIndex	number	Row index (0-based, in the current processed row array)
options	ScrollToRowOptions	Scroll alignment and behavior

---

scrollToRowById()

Scroll to make a row visible by its unique ID.

scrollToRowById(rowId: string, options: ScrollToRowOptions): void

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier (from getRowId)
options	ScrollToRowOptions	Scroll alignment and behavior

---