FrameworkAdapter

Since v0.2.9

Framework adapter interface for handling framework-specific component instantiation. Allows framework libraries (Angular, React, Vue) to register handlers that convert declarative light DOM elements into functional renderers/editors.

Example

// In @toolbox-web/grid-angular
class AngularGridAdapter implements FrameworkAdapter {
  canHandle(element: HTMLElement): boolean {
    return element.tagName.startsWith('APP-');
  }
  createRenderer(element: HTMLElement): ColumnViewRenderer {
    return (ctx) => {
      // Angular-specific instantiation logic
      const componentRef = createComponent(...);
      componentRef.setInput('value', ctx.value);
      return componentRef.location.nativeElement;
    };
  }
  createEditor(element: HTMLElement): ColumnEditorSpec {
    return (ctx) => {
      // Angular-specific editor with commit/cancel
      const componentRef = createComponent(...);
      componentRef.setInput('value', ctx.value);
      // Subscribe to commit/cancel outputs
      return componentRef.location.nativeElement;
    };
  }
}

// User registers adapter once in their app
GridElement.registerAdapter(new AngularGridAdapter(injector, appRef));

Methods

canHandle()

Determines if this adapter can handle the given element. Typically checks tag name, attributes, or other conventions.

canHandle(element: HTMLElement): boolean

Parameters

Name	Type	Description
element	HTMLElement

---

createRenderer()

Creates a view renderer function from a light DOM element. The renderer receives cell context and returns DOM or string. Returns undefined if no renderer template is registered, allowing the grid to use its default rendering.

createRenderer(element: HTMLElement): ColumnViewRenderer<TRow, TValue> | undefined

Parameters

Name	Type	Description
element	HTMLElement

---

createEditor()

Creates an editor spec from a light DOM element. The editor receives context with commit/cancel and returns DOM. Returns undefined if no editor template is registered, allowing the grid to use its default built-in editors.

createEditor(element: HTMLElement): ColumnEditorSpec<TRow, TValue> | undefined

Parameters

Name	Type	Description
element	HTMLElement

---

createHeaderRenderer() v2.15.0+

Creates a header cell renderer from a light DOM element (e.g. a slot or template on a <tbw-grid-column>). Receives HeaderCellContext and returns DOM / string for the entire header cell — the user is responsible for sort icons and filter buttons (use ctx.renderSortIcon() / ctx.renderFilterButton() helpers).

Resize handles are appended automatically by the grid for resizable columns regardless of which renderer path is active; do not render one yourself.

Returns undefined when the adapter has no header renderer registered for this element, letting the grid fall back to its built-in header.

Mirrors headerRenderer from BaseColumnConfig. Optional on the adapter — adapters that don’t expose a slot/template surface for full-header customization can omit it; callers must null-check.

createHeaderRenderer(element: HTMLElement): HeaderRenderer<TRow> | undefined

Parameters

Name	Type	Description
element	HTMLElement

---

createHeaderLabelRenderer() v2.15.0+

Creates a header label renderer from a light DOM element. The grid keeps ownership of the sort icon, filter button, and resize handle; the returned function only customizes the label content.

Returns undefined when the adapter has no header label renderer registered for this element.

Mirrors headerLabelRenderer from BaseColumnConfig. Optional on the adapter — see createHeaderRenderer for rationale.

createHeaderLabelRenderer(element: HTMLElement): HeaderLabelRenderer<TRow> | undefined

Parameters

Name	Type	Description
element	HTMLElement

---

createToolPanelRenderer()

Creates a tool panel renderer from a light DOM element. The renderer receives a container element and optionally returns a cleanup function.

createToolPanelRenderer(element: HTMLElement): (container: HTMLElement) => void | () => void | undefined

Parameters

Name	Type	Description
element	HTMLElement

---

getTypeDefault()

Gets type-level defaults from an application-level registry. Used by Angular’s GridTypeRegistry and React’s GridTypeProvider.

getTypeDefault(type: string, gridEl: HTMLElement): TypeDefault<TRow> | undefined

Parameters

Name	Type	Description
type	string	The column type (e.g., ‘date’, ‘currency’, ‘country’)
gridEl	HTMLElement	The owning <tbw-grid> element. Helps adapters resolve
the correct context provider in multi-grid scenarios.

Returns

TypeDefault<TRow> | undefined - Type defaults for renderer/editor, or undefined if not registered

---

processConfig()

Pre-process a grid config before the grid core applies it. Framework adapters use this to convert framework-specific component references (Angular classes, Vue components, React elements) to DOM-returning functions.

Called automatically by the grid’s set gridConfig setter when a __frameworkAdapter is present on the grid instance.

Must be idempotent — already-processed configs must pass through safely.

processConfig(config: GridConfig<TRow>): GridConfig<TRow>

Parameters

Name	Type	Description
config	GridConfig<TRow>	The raw grid config (may contain framework-specific values)

Returns

GridConfig<TRow> - Processed config with DOM-returning functions

---

releaseCell()

Called when a cell’s content is about to be wiped (e.g., when exiting edit mode, scroll-recycling a row, or rebuilding a row).

Framework adapters should use this to properly destroy cached views/components associated with the cell to prevent memory leaks.

releaseCell(cellEl: HTMLElement): void

Parameters

Name	Type	Description
cellEl	HTMLElement	The cell element whose content is being released

---

beginBatch() v2.14.0+

Open a teardown batch. Grid core wraps multi-cell teardown sequences (e.g., _clearRowPool, row-pool shrink, full row rebuild) where every affected cell will be detached from the DOM before the batch ends.

Adapters that normally synchronously commit framework teardown per releaseCell (React’s flushSync) should defer those commits until the matching endBatch call. Detached containers can then be pruned without emitting per-cell render warnings.

Calls may nest; adapters MUST track depth and only flush on the outermost endBatch.

beginBatch(gridEl: HTMLElement): void

Parameters

Name	Type	Description
gridEl	HTMLElement	The grid element whose adapter-managed cells are
being torn down. Adapters that key state per grid (e.g. one
PortalManager per grid) should scope the batch to this element.
Omitted only by callers without a grid reference.

---

endBatch() v2.14.0+

Close a teardown batch opened by beginBatch. Adapters should flush any deferred framework commits here (or rely on render-time detached-container filtering for adapters that don’t need a flush).

endBatch(gridEl: HTMLElement): void

Parameters

Name	Type	Description
gridEl	HTMLElement	Must match the element passed to the paired
beginBatch call.

---

unmount()

Unmount a specific framework container and free its resources.

Called by the grid core (e.g., MasterDetailPlugin) when a container created by the adapter is about to be removed from the DOM. The adapter should destroy the associated framework instance (React root, Vue app, Angular view) and remove it from tracking arrays.

unmount(container: HTMLElement): void

Parameters

Name	Type	Description
container	HTMLElement	The container element returned by a create* method

---

parseDetailElement()

Parse a <tbw-grid-detail> element and return a detail renderer function. Used by MasterDetailPlugin to support framework-specific detail templates.

parseDetailElement(element: Element): (row: TRow, rowIndex: number) => string | HTMLElement | undefined

Parameters

Name	Type	Description
element	Element

---

parseResponsiveCardElement()

Parse a <tbw-grid-responsive-card> element and return a card renderer function. Used by ResponsivePlugin to support framework-specific card templates.

parseResponsiveCardElement(element: Element): (row: TRow, rowIndex: number) => HTMLElement | undefined

Parameters

Name	Type	Description
element	Element

---