), }; function MyGrid({ rows }) { return ; } ``` #### Vue ```html ``` #### Angular ```typescript import { Component, input } from '@angular/core'; import { Grid } from '@toolbox-web/grid-angular'; import type { GridConfig } from '@toolbox-web/grid-angular'; // Loading spinner component (receives `size` input) @Component({ selector: 'app-spinner', template: `

`, }) export class SpinnerComponent { size = input<'large' | 'small'>('large'); } @Component({ imports: [Grid], template: ``, }) export class MyGridComponent { config: GridConfig = { loadingRenderer: SpinnerComponent, }; } ``` The `LoadingContext` provides a `size` property: `'large'` for the grid-wide overlay (up to 48×48 px) and `'small'` for row/cell indicators (sized to the row height). ```ts // CustomLoadingRendererDemo.astro import { queryGrid } from '@toolbox-web/grid'; const grid = await queryGrid('#demo-custom-loading-renderer', true); const toggleBtn = document.querySelector('[data-toggle="loading"]'); if (grid) { grid.columns = [ { field: 'id', header: 'ID', width: 80 }, { field: 'name', header: 'Name' }, { field: 'email', header: 'Email' }, { field: 'department', header: 'Department' }, ]; grid.rows = [ { id: 1, name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering' }, { id: 2, name: 'Bob Smith', email: 'bob@example.com', department: 'Marketing' }, { id: 3, name: 'Carol Davis', email: 'carol@example.com', department: 'Engineering' }, { id: 4, name: 'Dan Wilson', email: 'dan@example.com', department: 'Sales' }, { id: 5, name: 'Eve Brown', email: 'eve@example.com', department: 'HR' }, ]; grid.registerStyles('custom-loading', ` .progress-bar-container { position: absolute; top: 0; left: 0; right: 0; height: 4px; background: light-dark(rgba(0,0,0,0.08), rgba(255,255,255,0.08)); overflow: hidden; z-index: 1000; } .progress-bar { height: 100%; background: light-dark(#1976d2, #64b5f6); width: 30%; animation: progress-indeterminate 2s cubic-bezier(0.4,0,0.2,1) infinite; transform-origin: left; } @keyframes progress-indeterminate { 0% { transform: translateX(-100%); } 100% { transform: translateX(400%); } } `); grid.gridConfig = { getRowId: (row: { id: number }) => row.id, loadingRenderer: () => { const container = document.createElement('div'); container.className = 'progress-bar-container'; const bar = document.createElement('div'); bar.className = 'progress-bar'; container.appendChild(bar); return container; }, }; toggleBtn?.addEventListener('click', () => { grid.loading = !grid.loading; }); } ``` ### Empty State When the grid has no rows and is **not** loading, it shows a built-in message (`No data to display`, or `No matching rows` when a filter plugin hides every source row). Override the message with `emptyRenderer` — typically to surface error text from a failed fetch, or to provide an actionable empty state. ```typescript grid.gridConfig = { emptyRenderer: (ctx) => { if (loadError) return `Failed to load deals: ${loadError.message}`; if (ctx.filteredOut) return 'No deals match the current filter.'; return 'No deals to display.'; }, }; ``` The renderer receives an [`EmptyContext`](/grid/api/core/interfaces/emptycontext.md) with: - `sourceRowCount` — the number of input rows before any plugin filtering. - `filteredOut` — `true` when `sourceRowCount > 0` but all rows were hidden (e.g. by the [FilteringPlugin](/grid/plugins/filtering.md) or grouping). Return an `HTMLElement` for rich content (icons, buttons, multi-line layouts) or a `string` for plain text. Set `emptyRenderer: null` to suppress the overlay entirely. The overlay mounts inside the rows container by default. Set `emptyOverlay: 'grid'` to cover the entire grid (including the header) instead — useful for full-page error states. ```typescript grid.gridConfig = { emptyOverlay: 'grid', emptyRenderer: (ctx) => /* ... */, }; ``` :::note The loading overlay always wins: while `grid.loading === true` the empty overlay is hidden, even if there are zero rows. This avoids flashing an empty message during the initial fetch. ::: ```ts // EmptyStateDemo.astro import type { EmptyContext } from '@toolbox-web/grid'; import { queryGrid } from '@toolbox-web/grid'; type Row = { id: number; name: string; email: string; department: string }; const allRows: Array = [ { id: 1, name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering' }, { id: 2, name: 'Bob Smith', email: 'bob@example.com', department: 'Marketing' }, { id: 3, name: 'Carol Davis', email: 'carol@example.com', department: 'Engineering' }, { id: 4, name: 'Dan Wilson', email: 'dan@example.com', department: 'Sales' }, { id: 5, name: 'Eve Brown', email: 'eve@example.com', department: 'HR' }, ]; const grid = await queryGrid('#demo-empty-state', true); const statusEl = document.querySelector('[data-status]'); if (grid) { grid.columns = [ { field: 'id', header: 'ID', width: 80 }, { field: 'name', header: 'Name' }, { field: 'email', header: 'Email' }, { field: 'department', header: 'Department' }, ]; let errorMessage: string | null = null; const setStatus = (msg: string) => { if (statusEl) statusEl.textContent = msg; }; const emptyRenderer = (ctx: EmptyContext) => { if (errorMessage) { const wrapper = document.createElement('div'); wrapper.className = 'empty-error'; const icon = document.createElement('div'); icon.className = 'empty-error-icon'; icon.textContent = '⚠'; const title = document.createElement('div'); title.className = 'empty-error-title'; title.textContent = 'Failed to load data'; const detail = document.createElement('div'); detail.className = 'empty-error-detail'; detail.textContent = errorMessage; wrapper.append(icon, title, detail); return wrapper; } if (ctx.filteredOut) { return 'No employees match the current filter.'; } return 'No employees to display. Click "Load data" to fetch.'; }; grid.registerStyles('empty-state-demo', ` .empty-error { display: flex; flex-direction: column; align-items: center; gap: 6px; text-align: center; max-width: 320px; } .empty-error-icon { font-size: 28px; color: light-dark(#c62828, #ef9a9a); } .empty-error-title { font-weight: 600; color: light-dark(#c62828, #ef9a9a); } .empty-error-detail { font-size: 0.85em; color: light-dark(rgba(0,0,0,0.6), rgba(255,255,255,0.6)); } `); grid.gridConfig = { getRowId: (row: Row) => row.id, emptyRenderer, }; grid.rows = []; setStatus('Empty state — showing default message.'); document.querySelector('[data-action="load"]')?.addEventListener('click', () => { errorMessage = null; grid.rows = allRows; setStatus(`Loaded ${allRows.length} rows.`); }); document.querySelector('[data-action="clear"]')?.addEventListener('click', () => { errorMessage = null; grid.rows = []; setStatus('Cleared — showing empty message.'); }); document.querySelector('[data-action="error"]')?.addEventListener('click', () => { errorMessage = 'Network request timed out after 30s'; grid.rows = []; setStatus('Simulated error — showing custom error renderer.'); }); } ``` --- ## Variable Row Heights By default all rows share a fixed height (`--tbw-row-height`, default 28 px). You can configure per-row heights using a function. ### Configuration ```typescript // Fixed height for all rows grid.gridConfig = { rowHeight: 56 }; // Per-row height function grid.gridConfig = { rowHeight: (row, index) => (row.hasDetails ? 80 : 40), }; ``` If your function returns `undefined` for a row, the grid **auto-measures** that row's actual DOM height after rendering. ### How Auto-Measurement Works 1. The grid renders rows with an estimated height. 2. After paint, it reads `offsetHeight` for each rendered row. 3. Measured heights are cached and the position cache is rebuilt. 4. A `ResizeObserver` watches for late layout shifts (font loading, lazy images) and re-measures automatically. ### Row Identity for Height Caching Measured heights are cached using: - **`getRowId`** / `rowId` — preferred, survives sort/filter changes - **Object reference** (WeakMap) — fallback when no ID is configured Provide `getRowId` for best results when rows are re-sorted, filtered, or grouped. ### Plugin-Provided Heights Plugins can override row heights by implementing the `getRowHeight(row, index)` hook. The **MasterDetailPlugin** and **ResponsivePlugin** use this to provide expanded-row heights. ### Performance Considerations - **Fixed heights** are fastest — the grid can calculate positions with pure math. - **Function-based heights** add a per-row function call during position-cache rebuilds. - **Auto-measured heights** require a DOM read pass after rendering — avoid for 10 k+ row grids unless combined with `getRowId` caching. - When mixing fixed and auto-measured rows, return a number for most rows and `undefined` only for rows that need measurement. ```ts // VariableRowHeightDemo.astro import '@toolbox-web/grid'; import { queryGrid, type CellRenderContext } from '@toolbox-web/grid'; interface Employee { id: number; name: string; role: string; department: string; notes: string; } const container = document.getElementById('variable-row-height-demo'); const grid = queryGrid('tbw-grid', container!); if (!grid) throw new Error('Grid not found'); grid.gridConfig = { columns: [ { field: 'id', header: 'ID', width: 60 }, { field: 'name', header: 'Name', width: 140 }, { field: 'role', header: 'Role', width: 100 }, { field: 'department', header: 'Department', width: 120 }, { field: 'notes', header: 'Notes', renderer: (ctx: CellRenderContext) => { const { row } = ctx; // For demonstration, render notes with a tooltip for tall rows const cell = document.createElement('div'); cell.textContent = row.notes; if (tallRowIds.has(row.id)) { cell.title = 'This row has extended notes'; cell.style.whiteSpace = 'pre-wrap'; cell.style.fontStyle = 'italic'; } return cell; } }, ], getRowId: (row) => String(row.id), rowHeight: (row) => { // Rows with ids in tallRowIds get a taller height if (tallRowIds.has(row.id)) return 56; return undefined; // use default height }, }; // Generate 150 rows — a handful have long notes that warrant taller rows const tallRowIds = new Set([5, 18, 42, 77, 130]); const departments = ['Engineering', 'Marketing', 'Sales', 'Support', 'Finance', 'HR', 'Legal', 'Design']; const roles = ['Manager', 'Senior', 'Junior', 'Lead', 'Intern', 'Director', 'VP', 'Analyst']; grid.rows = Array.from({ length: 150 }, (_, i) => { const id = i + 1; const isTall = tallRowIds.has(id); return { id, name: `Employee ${id}`, role: roles[i % roles.length], department: departments[i % departments.length], notes: isTall ? `This employee has extended notes that require a taller row. ` + `Additional context: performance review pending, cross-team ` + `collaboration active, mentoring two junior engineers.` : `Standard note for employee ${id}.`, }; }); ``` --- ## Events The grid dispatches standard `CustomEvent`s for user interactions — clicks, sort changes, column resizes, and more. Plugin-specific events (selection, editing, filtering, etc.) are also available when those plugins are active. For the complete event reference — including listening patterns per framework, cancelable events, and all plugin events — see the **[Events section](/grid/api-reference.md#events)** of the API Reference. --- ## Methods The `` element exposes public methods for programmatic control — data manipulation, focus management, column state persistence, custom styles, shell control, loading indicators, row animation, and more. Use `createGrid()` or `queryGrid()` for type-safe access. For the complete method reference — including signatures, return types, and factory functions — see the **[API Reference](/grid/api-reference.md#methods)** page. --- ## See Also - [Getting Started](/grid/getting-started.md) — Installation and setup - [Common Patterns](/grid/guides/common-patterns.md) — Full application recipes - [Plugins](/grid/plugins.md) — Extend with selection, filtering, editing, and more - [Theming](/grid/guides/theming.md) — CSS custom properties, dark mode, themes - [Architecture](/grid/architecture.md) — Render scheduler, Light DOM, design decisions - [Plugin System](/grid/plugin-development/custom-plugins.md) — Build your own plugins --- # Demos > Full-featured demo applications showcasing @toolbox-web/grid with 15+ plugins, custom editors, master-detail, and more. ## Reference Implementation — Employee Management (advanced, end-to-end) This is the canonical advanced grid in this project: ~15 columns mixing text, number, date, select and boolean; custom renderers and editors; master-detail; multi-sort; per-column filtering; row grouping; CSV/Excel export; clipboard; context menu; undo/redo; pinned rows; and side tool panels. In the cross-framework `llms-full.txt` (and this page's `.md`) the source below is the **vanilla, framework-agnostic implementation** — the `GridConfig` object is portable verbatim to the React, Angular and Vue adapters (per RULE 0 in the [Introduction](/grid/introduction.md): one `gridConfig` over fragmented props). In a per-framework `llms-full-{react,vue,angular}.txt` corpus the same reference is shown as that framework's **native implementation** (adapter components plus JSX / SFC / component renderers and editors), drawn from `demos/{angular,react,vue}/src/demos/employee-management/`. Only the row type and seed data (`demos/shared/employee-management/`) are shared across all of them. Read the files in this order: the domain model, then the grid config (columns + `features` + manual `plugins`), then the custom renderers, editors and tool panels, then the factory or component that wires them together. ```ts // demos/shared/employee-management/types.ts /** * Shared Data Models for Employee Management Demo * * These type definitions are shared across all framework implementations * (Vanilla, React, Angular, Vue) of the Employee Management demo. */ // Re-export grid element type for easier imports in demos export type { TbwGrid as GridElement } from '@toolbox-web/grid'; /** * Represents a project that an employee is working on or has completed. */ export interface Project { id: string; name: string; role: string; hoursLogged: number; status: 'active' | 'completed' | 'on-hold'; } /** * Represents a quarterly performance review for an employee. */ export interface PerformanceReview { year: number; quarter: string; score: number; notes: string; } /** * Represents an employee record in the HR management system. */ export interface Employee { id: number; firstName: string; lastName: string; email: string; department: string; team: string; title: string; level: 'Junior' | 'Mid' | 'Senior' | 'Lead' | 'Principal' | 'Director'; salary: number; bonus: number; status: 'Active' | 'On Leave' | 'Remote' | 'Contract' | 'Terminated'; hireDate: string; lastPromotion: string | null; manager: string | null; location: string; timezone: string; skills: string[]; rating: number; completedProjects: number; activeProjects: Project[]; performanceReviews: PerformanceReview[]; isTopPerformer: boolean; } /** * Configuration options for the demo (used by story controls). */ export interface DemoConfig { rowCount: number; enableSelection: boolean; enableFiltering: boolean; enableSorting: boolean; enableEditing: boolean; enableMasterDetail: boolean; enableRowGrouping: boolean; } ``` ```ts // demos/vanilla/src/demos/employee-management/grid-config.ts /** * Grid Configuration for Employee Management Demo * * This file demonstrates the `features` configuration API for @toolbox-web/grid. * Most plugins are configured declaratively via `features: { ... }` on the grid config. * The PinnedRowsPlugin is configured manually via `plugins: [...]` to show both approaches. */ // Feature side-effect imports — register feature factories in the core registry. // Each import is tiny (~200-300 bytes) and only includes the factory + type augmentation. import '@toolbox-web/grid/features/clipboard'; import '@toolbox-web/grid/features/column-virtualization'; import '@toolbox-web/grid/features/context-menu'; import '@toolbox-web/grid/features/editing'; import '@toolbox-web/grid/features/export'; import '@toolbox-web/grid/features/filtering'; import '@toolbox-web/grid/features/grouping-columns'; import '@toolbox-web/grid/features/grouping-rows'; import '@toolbox-web/grid/features/master-detail'; import '@toolbox-web/grid/features/multi-sort'; import '@toolbox-web/grid/features/pinned-columns'; import '@toolbox-web/grid/features/pinned-rows'; import '@toolbox-web/grid/features/reorder-columns'; import '@toolbox-web/grid/features/responsive'; import '@toolbox-web/grid/features/selection'; import '@toolbox-web/grid/features/shell'; import '@toolbox-web/grid/features/undo-redo'; import '@toolbox-web/grid/features/visibility'; // PinnedRowsPlugin is imported directly to demonstrate the manual plugins approach. // Built-in panel renderers are imported alongside it for the new slots[] API. import type { GridConfig } from '@toolbox-web/grid'; import { filteredCountPanel, PinnedRowsPlugin, rowCountPanel } from '@toolbox-web/grid/plugins/pinned-rows'; import { DEPARTMENTS, type Employee } from '@demo/shared/employee-management'; import { bonusSliderEditor, dateEditor, starRatingEditor, statusSelectEditor } from './editors'; import { createDetailRenderer, createResponsiveCardRenderer, ratingRenderer, statusViewRenderer, topPerformerRenderer, } from './renderers'; // ============================================================================= // COLUMN GROUPS // ============================================================================= /** * Column groups for the employee grid. * Used by GroupingColumnsPlugin to create grouped headers. * Also used by column-move handler to enforce group constraints. */ export const COLUMN_GROUPS = [ { id: 'employee', header: 'Employee Info', children: ['firstName', 'lastName', 'email'] }, { id: 'organization', header: 'Organization', children: ['department', 'team', 'title', 'level'] }, { id: 'compensation', header: 'Compensation', children: ['salary', 'bonus'] }, { id: 'status', header: 'Status & Performance', children: ['status', 'hireDate', 'rating', 'isTopPerformer', 'location'], }, ]; // ============================================================================= // CONFIGURATION OPTIONS // ============================================================================= /** * Options for configuring the grid. * Toggle features on/off based on demo requirements. */ export interface GridConfigOptions { enableSelection: boolean; enableFiltering: boolean; enableSorting: boolean; enableEditing: boolean; enableMasterDetail: boolean; enableRowGrouping?: boolean; } // ============================================================================= // GRID CONFIGURATION FACTORY // ============================================================================= /** * Creates a complete grid configuration for the employee management demo. * * This configuration includes: * - 15 columns with various types (text, number, date, select, boolean) * - Custom editors (star rating, bonus slider, status select, date picker) * - Custom renderers (status badges, rating colors, top performer badge) * - Shell header with title * - Multiple plugins for advanced features * * @example * ```ts * const config = createGridConfig({ * enableSelection: true, * enableFiltering: true, * enableSorting: true, * enableEditing: true, * enableMasterDetail: true, * }); * * grid.gridConfig = config; * ``` */ export function createGridConfig(options: GridConfigOptions): GridConfig { const { enableSelection, enableFiltering, enableSorting, enableEditing, enableMasterDetail, enableRowGrouping = false, } = options; return { fitMode: 'fixed', // Column groups for grouped headers columnGroups: COLUMN_GROUPS, // Column definitions columns: [ { field: 'id', header: 'ID', type: 'number', width: 70, sortable: true }, { field: 'firstName', header: 'First Name', minWidth: 100, editable: enableEditing, sortable: true, resizable: true, }, { field: 'lastName', header: 'Last Name', minWidth: 100, editable: enableEditing, sortable: true, resizable: true, }, { field: 'email', header: 'Email', minWidth: 200, resizable: true }, { field: 'department', header: 'Dept', width: 120, sortable: true, editable: enableEditing, type: 'select', options: DEPARTMENTS.map((d) => ({ label: d, value: d })), }, { field: 'team', header: 'Team', width: 110, sortable: true }, { field: 'title', header: 'Title', minWidth: 160, editable: enableEditing, resizable: true }, { field: 'level', header: 'Level', width: 90, sortable: true, editable: enableEditing, type: 'select', options: ['Junior', 'Mid', 'Senior', 'Lead', 'Principal', 'Director'].map((l) => ({ label: l, value: l })), }, { field: 'salary', header: 'Salary', type: 'number', width: 110, editable: enableEditing, sortable: true, resizable: true, format: (v: number) => v.toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 }), }, { field: 'bonus', header: 'Bonus', type: 'number', width: 180, sortable: true, editable: enableEditing, editor: bonusSliderEditor, format: (v: number) => v.toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 }), }, { field: 'status', header: 'Status', width: 140, sortable: true, editable: enableEditing, editor: statusSelectEditor, renderer: statusViewRenderer, }, { field: 'hireDate', header: 'Hire Date', type: 'date', width: 130, sortable: true, editable: enableEditing, editor: dateEditor, }, { field: 'rating', header: 'Rating', type: 'number', width: 120, sortable: true, editable: enableEditing, editor: starRatingEditor, renderer: ratingRenderer, }, { field: 'isTopPerformer', header: '⭐', type: 'boolean', width: 50, sortable: false, renderer: topPerformerRenderer, }, { field: 'location', header: 'Location', width: 110, sortable: true }, ], // Grid-wide feature toggles (used by plugins that support enable/disable) sortable: enableSorting, filterable: enableFiltering, selectable: enableSelection, // Declarative feature configuration — the recommended approach. // Each key corresponds to a feature side-effect import above. // The grid creates plugin instances from these configs automatically. features: { // Shell (header, tool panels) — best-practice feature opt-in. shell: { header: { title: 'Employee Management System (JS)', }, toolPanel: { position: 'right' as const, width: 300 }, }, selection: 'range', multiSort: true, filtering: { debounceMs: 200 }, // EditingPlugin always loaded; toggle via editOn to avoid validation errors // when columns have `editable: true` editing: enableEditing ? 'dblclick' : { editOn: false }, clipboard: true, contextMenu: true, reorderColumns: true, groupingColumns: true, pinnedColumns: true, columnVirtualization: true, visibility: true, // Responsive plugin for mobile/narrow layouts responsive: { breakpoint: 700, cardRenderer: (row: Employee) => createResponsiveCardRenderer(row), cardRowHeight: 80, hiddenColumns: ['id', 'email', 'team', 'level', 'bonus', 'hireDate', 'isTopPerformer', 'location'], }, // Row grouping (works alongside master-detail) ...(enableRowGrouping ? { groupingRows: { groupOn: (row: unknown) => (row as Employee).department, defaultExpanded: false, showRowCount: true, aggregators: { salary: 'sum', rating: (rows: Record[], field: string) => { const sum = rows.reduce((acc, row) => acc + (Number(row[field]) || 0), 0); return rows.length ? (sum / rows.length).toFixed(1) : ''; }, }, }, } : {}), // Master-detail (works alongside row grouping — details appear on data rows within groups) ...(enableMasterDetail ? { masterDetail: { detailRenderer: (row: unknown) => createDetailRenderer(row as Employee), showExpandColumn: true, animation: 'slide' as const, }, } : {}), undoRedo: { maxHistorySize: 100 }, export: true, }, // Manual plugins array — PinnedRowsPlugin kept here to demonstrate // that `features` and `plugins` can be mixed in the same config. plugins: [ new PinnedRowsPlugin({ slots: [ { id: 'totals', position: 'bottom', label: 'Summary:', cells: { salary: (rows: unknown[]) => (rows as Employee[]) .reduce((acc, r) => acc + (r.salary || 0), 0) .toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 }), bonus: (rows: unknown[]) => (rows as Employee[]) .reduce((acc, r) => acc + (r.bonus || 0), 0) .toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 }), rating: (rows: unknown[]) => { const vals = (rows as Employee[]).map((r) => r.rating).filter(Boolean); return vals.length ? `Avg: ${(vals.reduce((a, b) => a + b, 0) / vals.length).toFixed(2)}` : ''; }, }, }, { id: 'count', position: 'bottom', render: rowCountPanel() }, { id: 'filtered', position: 'bottom', render: filteredCountPanel() }, ], }), ], }; } ``` ```ts // demos/vanilla/src/demos/employee-management/renderers.ts /** * View Renderers for the Vanilla Employee Management Demo * * View renderers customize how cell values are displayed in read mode. */ import type { Employee } from '@demo/shared/employee-management'; /** * Renders a status badge with color-coded styling. */ export const statusViewRenderer = ({ value }: { value: string }): string => { const statusClass = value.toLowerCase().replace(/\s+/g, '-'); return `${value}`; }; /** * Renders a star indicator for top performer status. */ export const topPerformerRenderer = ({ value }: { value: boolean }): string => { return value ? '★' : '☆'; }; /** * Renders a rating value with color coding based on score. */ export const ratingRenderer = ({ value }: { value: number }): string => { const level = value >= 4.5 ? 'high' : value >= 3.5 ? 'medium' : 'low'; return `${value.toFixed(1)} ★`; }; /** * Creates a detail panel element for master-detail view. * Shows employee's active projects, performance reviews, and skills. */ export const createDetailRenderer = (employee: Employee): HTMLElement => { const container = document.createElement('div'); container.className = 'detail-panel'; const projectsHtml = employee.activeProjects .map( (p) => `` + `${p.id}` + `${p.name}` + `${p.role}` + `${p.hoursLogged}h` + `` + `${p.status}` + ``, ) .join(''); const reviewsHtml = employee.performanceReviews .slice(-4) .map((r) => { const scoreLevel = r.score >= 4 ? 'high' : r.score >= 3 ? 'medium' : 'low'; return ( `

` + `

${r.quarter} ${r.year}

` + `

${r.score.toFixed(1)}

` + `

${r.notes}

` + `

` ); }) .join(''); const skillsHtml = employee.skills.map((s) => `${s}`).join(''); container.innerHTML = `

` + `

Active Projects

` + `` + `` + `` + `` + `` + `` + `` + `` + `${projectsHtml}` + `

ID	Project	Role	Hours	Status

` + `

Performance Reviews

` + `

${reviewsHtml}

` + `

Skills

` + `${skillsHtml}` + `

` + `

`; return container; }; /** * Creates a responsive card element for mobile/narrow layouts. * Shows compact employee info with avatar placeholder, status badge, and key metrics. */ export const createResponsiveCardRenderer = (employee: Employee): HTMLElement => { const card = document.createElement('div'); card.className = 'responsive-employee-card'; // Get initials for avatar placeholder const initials = `${employee.firstName.charAt(0)}${employee.lastName.charAt(0)}`; // Determine department color const deptColors: Record = { Engineering: '#3b82f6', Marketing: '#ec4899', Sales: '#f59e0b', HR: '#10b981', Finance: '#6366f1', Legal: '#8b5cf6', Operations: '#14b8a6', 'Customer Support': '#f97316', }; const deptColor = deptColors[employee.department] ?? '#6b7280'; // Format salary const salary = employee.salary.toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0, }); // Status class const statusClass = employee.status.toLowerCase().replace(/\s+/g, '-'); card.innerHTML = `

` + `${initials}` + `

` + `

` + `` + `

${employee.title}

` + `

` + `${employee.department}` + `•` + `${salary}` + `•` + `${employee.rating.toFixed(1)} ★` + `${employee.isTopPerformer ? '⭐' : ''}` + `

` + `

`; return card; }; ``` ```ts // demos/vanilla/src/demos/employee-management/editors.ts /** * Custom Cell Editors for the Vanilla Employee Management Demo * * Each editor demonstrates different interaction patterns for inline editing. */ import type { Employee } from '@demo/shared/employee-management'; import type { ColumnEditorContext } from '@toolbox-web/grid'; /** * Interactive 5-star rating editor with keyboard support. */ export const starRatingEditor = (ctx: ColumnEditorContext): HTMLElement => { const container = document.createElement('div'); container.className = 'star-rating-editor'; container.setAttribute('tabindex', '0'); let currentValue = ctx.value ?? 3; const renderStars = () => { container.innerHTML = ''; for (let i = 1; i <= 5; i++) { const star = document.createElement('span'); const filled = i <= Math.round(currentValue); star.textContent = filled ? '★' : '☆'; star.className = `star-rating-editor__star ${filled ? 'star-rating-editor__star--filled' : 'star-rating-editor__star--empty'}`; star.dataset.value = String(i); star.addEventListener('click', (e) => { e.stopPropagation(); currentValue = i; renderStars(); ctx.commit(i); }); container.appendChild(star); } const label = document.createElement('span'); label.textContent = ` ${currentValue.toFixed(1)}`; label.className = 'star-rating-editor__label'; container.appendChild(label); }; container.addEventListener('keydown', (e) => { if (e.key === 'ArrowLeft' && currentValue > 1) { currentValue = Math.max(1, currentValue - 0.5); renderStars(); } else if (e.key === 'ArrowRight' && currentValue < 5) { currentValue = Math.min(5, currentValue + 0.5); renderStars(); } else if (e.key === 'Enter') { ctx.commit(currentValue); } else if (e.key === 'Escape') { ctx.cancel(); } }); renderStars(); // Note: Don't auto-focus here - the grid handles focus via beginBulkEdit/inlineEnterEdit // Auto-focusing here would cause all editors to fight for focus, with the last one winning return container; }; /** * Bonus slider editor with percentage display. */ export const bonusSliderEditor = (ctx: ColumnEditorContext): HTMLElement => { const container = document.createElement('div'); container.className = 'bonus-slider-editor'; const salary = ctx.row.salary || 100000; const minBonus = Math.round(salary * 0.02); const maxBonus = Math.round(salary * 0.25); let currentValue = ctx.value ?? Math.round(salary * 0.1); const slider = document.createElement('input'); slider.type = 'range'; slider.min = String(minBonus); slider.max = String(maxBonus); slider.value = String(currentValue); slider.className = 'bonus-slider-editor__slider'; const display = document.createElement('span'); const updateDisplay = () => { const percent = ((currentValue / salary) * 100).toFixed(1); const colorClass = parseFloat(percent) >= 15 ? 'bonus-slider-editor__value--high' : parseFloat(percent) >= 10 ? 'bonus-slider-editor__value--medium' : 'bonus-slider-editor__value--low'; display.innerHTML = `$${currentValue.toLocaleString()} (${percent}%)`; }; display.className = 'bonus-slider-editor__display'; updateDisplay(); slider.addEventListener('input', () => { currentValue = parseInt(slider.value, 10); updateDisplay(); }); slider.addEventListener('change', () => ctx.commit(currentValue)); slider.addEventListener('keydown', (e) => { if (e.key === 'Enter') ctx.commit(currentValue); else if (e.key === 'Escape') ctx.cancel(); }); container.appendChild(slider); container.appendChild(display); // Note: Don't auto-focus here - the grid handles focus via beginBulkEdit/inlineEnterEdit return container; }; /** * Status selection editor with colored badges. */ export const statusSelectEditor = (ctx: ColumnEditorContext): HTMLElement => { const container = document.createElement('div'); container.className = 'status-select-editor'; const statusConfig: Record = { Active: { bg: '#d4edda', text: '#155724', icon: '✓' }, Remote: { bg: '#cce5ff', text: '#004085', icon: '🏠' }, 'On Leave': { bg: '#fff3cd', text: '#856404', icon: '🌴' }, Contract: { bg: '#e2e3e5', text: '#383d41', icon: '📄' }, Terminated: { bg: '#f8d7da', text: '#721c24', icon: '✗' }, }; const select = document.createElement('select'); select.className = 'status-select-editor__select'; Object.entries(statusConfig).forEach(([status, config]) => { const option = document.createElement('option'); option.value = status; option.textContent = `${config.icon} ${status}`; option.selected = status === ctx.value; select.appendChild(option); }); container.appendChild(select); select.addEventListener('change', () => ctx.commit(select.value)); select.addEventListener('keydown', (e) => { if (e.key === 'Escape') { e.preventDefault(); ctx.cancel(); } }); // Note: Don't auto-focus here - the grid handles focus via beginBulkEdit/inlineEnterEdit return container; }; /** * Native HTML5 date input editor. */ export const dateEditor = (ctx: ColumnEditorContext): HTMLElement => { const input = document.createElement('input'); input.type = 'date'; input.value = ctx.value || ''; input.className = 'date-editor'; input.addEventListener('change', () => ctx.commit(input.value)); input.addEventListener('keydown', (e) => { if (e.key === 'Enter') ctx.commit(input.value); else if (e.key === 'Escape') ctx.cancel(); }); // Note: Don't auto-focus here - the grid handles focus via beginBulkEdit/inlineEnterEdit return input; }; ``` ```ts // demos/vanilla/src/demos/employee-management/tool-panels.ts /** * Tool Panels for the Vanilla Employee Management Demo * * Tool panels are registered with the grid's shell and appear in a sidebar. * This demonstrates how clean the API is - no type casting needed! */ import { DEPARTMENTS, type Employee, type GridElement } from '@demo/shared/employee-management'; import { shadowDomStyles } from '@demo/shared/employee-management/styles'; import { FilteringPlugin } from '@toolbox-web/grid/all'; /** * Injects all demo styles into the grid. * Uses the grid's registerStyles() API. */ export function injectToolPanelStyles(grid: GridElement): void { grid.registerStyles?.('demo-styles', shadowDomStyles); } /** * Registers the Quick Filters tool panel. */ export function registerQuickFiltersPanel(grid: GridElement): void { grid.getPluginByName('shell')?.registerToolPanel({ id: 'quick-filters', title: 'Quick Filters', icon: '🔍', tooltip: 'Apply quick filters to the data', order: 10, render: (container: HTMLElement) => { const content = document.createElement('div'); content.className = 'tool-panel-content'; content.innerHTML = `

`; container.appendChild(content); // Pill toggle styling content.querySelectorAll('.level-filter, .status-filter').forEach((input) => { input.addEventListener('change', (e) => { const cb = e.target as HTMLInputElement; cb.closest('.filter-pill')?.classList.toggle('filter-pill--active', cb.checked); }); }); // Rating slider const ratingSlider = content.querySelector('#rating-filter') as HTMLInputElement; const ratingValue = content.querySelector('#rating-value') as HTMLElement; ratingSlider?.addEventListener('input', () => (ratingValue.textContent = `≥ ${ratingSlider.value}`)); // Apply filters - clean API, no type casting needed! content.querySelector('#apply-filters')?.addEventListener('click', () => { const plugin = grid.getPlugin?.(FilteringPlugin); if (!plugin) return; plugin.clearAllFilters(); const dept = (content.querySelector('#dept-filter') as HTMLSelectElement).value; if (dept) plugin.setFilter('department', { type: 'text', operator: 'equals', value: dept }); const levels = Array.from(content.querySelectorAll('.level-filter:checked')).map( (el) => (el as HTMLInputElement).value, ); if (levels.length) plugin.setFilter('level', { type: 'set', operator: 'in', value: levels }); const statuses = Array.from(content.querySelectorAll('.status-filter:checked')).map( (el) => (el as HTMLInputElement).value, ); if (statuses.length) plugin.setFilter('status', { type: 'set', operator: 'in', value: statuses }); const minRating = parseFloat(ratingSlider.value); if (minRating > 0) plugin.setFilter('rating', { type: 'number', operator: 'greaterThanOrEqual', value: minRating }); if ((content.querySelector('#top-performer-filter') as HTMLInputElement).checked) { plugin.setFilter('isTopPerformer', { type: 'boolean', operator: 'equals', value: true }); } }); // Clear filters content.querySelector('#clear-filters')?.addEventListener('click', () => { grid.getPlugin?.(FilteringPlugin)?.clearAllFilters(); (content.querySelector('#dept-filter') as HTMLSelectElement).value = ''; content.querySelectorAll('.level-filter, .status-filter').forEach((input) => { (input as HTMLInputElement).checked = false; input.closest('.filter-pill')?.classList.remove('filter-pill--active'); }); ratingSlider.value = '0'; ratingValue.textContent = '≥ 0'; (content.querySelector('#top-performer-filter') as HTMLInputElement).checked = false; }); return () => content.remove(); }, }); } /** * Registers the Analytics tool panel. */ export function registerAnalyticsPanel(grid: GridElement): void { grid.getPluginByName('shell')?.registerToolPanel({ id: 'analytics', title: 'Analytics', icon: '📈', tooltip: 'View data analytics and insights', order: 20, render: (container: HTMLElement) => { const rows = grid.rows || []; const totalSalary = rows.reduce((sum, r) => sum + r.salary, 0); const avgSalary = totalSalary / rows.length; const avgRating = rows.reduce((sum, r) => sum + r.rating, 0) / rows.length; const topPerformers = rows.filter((r) => r.isTopPerformer).length; const deptCounts = rows.reduce( (acc, r) => ({ ...acc, [r.department]: (acc[r.department] || 0) + 1 }), {} as Record, ); const sortedDepts = Object.entries(deptCounts).sort((a, b) => b[1] - a[1]); const largestDept = sortedDepts[0]; const formatCurrency = (v: number) => v.toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 }); const content = document.createElement('div'); content.className = 'analytics-content'; content.innerHTML = `

Total Payroll

${formatCurrency(totalSalary)}

Avg Salary

${formatCurrency(avgSalary)}

Avg Rating

${avgRating.toFixed(1)} ★

Top Performers

${topPerformers}

Department Distribution

${sortedDepts .slice(0, 6) .map( ([dept, count]) => `

${dept}

${count}

`, ) .join('')}

Largest Department

${largestDept?.[0] || 'N/A'} (${largestDept?.[1] || 0} employees)

`; container.appendChild(content); return () => content.remove(); }, }); } ``` ```ts // demos/vanilla/src/demos/employee-management/grid-factory.ts /** * Employee Management Grid Factory * * Pure factory function that creates a fully configured employee grid element. * Decoupled from the route shell so the docs site can call `createEmployeeGrid()` * directly via the `@demo/vanilla` alias. */ // Import shared demo styles (applies to document) import '@demo/shared/employee-management/demo-styles.css'; // Import the grid component (registers custom element) import '@toolbox-web/grid'; // Import grid factory and plugins import { createGrid, type DataGridElement } from '@toolbox-web/grid/all'; // Import shared data generators and types import { generateEmployees, type Employee } from '@demo/shared/employee-management'; // Import grid configuration from separate file import { createGridConfig, type GridConfigOptions } from './grid-config'; // Import tool panel registration import { injectToolPanelStyles, registerAnalyticsPanel, registerQuickFiltersPanel } from './tool-panels'; /** * Options for creating an employee grid. * Extends GridConfigOptions with row count. */ export interface EmployeeGridOptions extends GridConfigOptions { rowCount: number; } /** * Creates a fully configured employee management grid. * * @param options - Configuration options for the grid * @returns The configured grid element */ export function createEmployeeGrid(options: EmployeeGridOptions): DataGridElement { const { rowCount, ...configOptions } = options; // Create the grid element using the typed factory function const grid = createGrid(); grid.id = 'employee-grid'; grid.className = 'demo-grid'; // Create toolbar buttons container (users have full control over button HTML) const toolButtons = document.createElement('tbw-grid-tool-buttons'); const exportCsvBtn = document.createElement('button'); exportCsvBtn.className = 'tbw-toolbar-btn'; exportCsvBtn.setAttribute('title', 'Export CSV'); exportCsvBtn.setAttribute('aria-label', 'Export CSV'); exportCsvBtn.textContent = '📄'; exportCsvBtn.onclick = () => grid.getPluginByName?.('export')?.exportCsv?.({ fileName: 'employees' }); const exportExcelBtn = document.createElement('button'); exportExcelBtn.className = 'tbw-toolbar-btn'; exportExcelBtn.setAttribute('title', 'Export Excel'); exportExcelBtn.setAttribute('aria-label', 'Export Excel'); exportExcelBtn.textContent = '📊'; exportExcelBtn.onclick = () => grid.getPluginByName?.('export')?.exportExcel?.({ fileName: 'employees' }); toolButtons.appendChild(exportCsvBtn); toolButtons.appendChild(exportExcelBtn); grid.appendChild(toolButtons); // Apply configuration grid.gridConfig = createGridConfig(configOptions); // Set initial data grid.rows = generateEmployees(rowCount); // Register tool panels and inject styles after grid is ready grid.ready?.().then(() => { registerQuickFiltersPanel(grid); registerAnalyticsPanel(grid); grid.refreshShellHeader?.(); injectToolPanelStyles(grid); }); return grid; } // Re-export config helpers so consumers can build their own grid variants export { createGridConfig, type GridConfigOptions } from './grid-config'; ``` --- # Architecture > Internal architecture of @toolbox-web/grid — configuration system, render scheduler, virtualization, plugin lifecycle, and light DOM design. This page describes the internal architecture of `@toolbox-web/grid`. It's intended for contributors, plugin developers, and anyone who wants to understand how the grid works under the hood. ## Design Philosophy 1. **Light DOM** — No Shadow DOM. The grid renders directly into the element, allowing full CSS customization. 2. **Single Source of Truth** — All configuration converges into `effectiveConfig`, which is the only state read by rendering logic. 3. **Plugin-First** — Features like selection, editing, and filtering are plugins, not core code. This keeps the core small and tree-shakeable. 4. **Web Standards** — Built on Custom Elements, CSS Custom Properties, `adoptedStyleSheets`, and standard DOM APIs. 5. **Framework-Agnostic** — Pure TypeScript/HTML, no runtime framework dependencies. ## Component Overview ``` ┌───────────────────────────────────────────────────────┐ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Light DOM │ │ │ │ ┌───────────────────────────────────────────┐ │ │ │ │ │ Header Row │ │ │ │ │ └───────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────┐ │ │ │ │ │ Rows Viewport (scrollable) │ │ │ │ │ │ ┌─────────────────────────────────────┐ │ │ │ │ │ │ │ Spacer (virtual scroll height) │ │ │ │ │ │ │ ├─────────────────────────────────────┤ │ │ │ │ │ │ │ Visible Rows (row pool) │ │ │ │ │ │ │ └─────────────────────────────────────┘ │ │ │ │ │ └───────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────┘ ``` ## Component Lifecycle ``` constructor() └── Create internal state objects └── Initialize render scheduler connectedCallback() └── Parse light DOM children (, ) └── Merge configuration (gridConfig + columns + fitMode + light DOM) └── Attach plugins (validate dependencies, call onAttach) └── Render header + rows └── Set up scroll listener, resize observer attributeChangedCallback() └── Map attribute → property setter disconnectedCallback() └── Abort disconnect signal (plugins clean up) └── Remove event listeners └── Disconnect resize observer ``` --- ## Configuration Architecture The grid follows a **single source of truth** pattern. All configuration inputs converge into one `effectiveConfig` object, which is then used for all rendering and behavior. ### Why Single Source of Truth? - **Predictable behavior**: One canonical config means no ambiguity about which setting applies - **Easy debugging**: Inspect `effectiveConfig` to see exactly what the grid is using - **Flexible input**: Users can configure via the method most convenient for their use case - **Plugin-friendly**: Plugins can read/modify config through one consistent interface ### Input Sources Users can configure the grid through multiple input methods: ```mermaid flowchart TB subgraph inputs["INPUT SOURCES"] direction TB A["gridConfig
property"] B["columns
property"] C["fitMode
property"] subgraph lightdom["LIGHT DOM"] D["<tbw-grid-column>
field, header"] E["<tbw-grid-header>
title"] end end A --> F B --> F C --> F D --> F E --> F F["ConfigManager.merge()
single merge point"] F --> G["#effectiveConfig
canonical config
◀ SINGLE SOURCE OF TRUTH"] G --> H["DERIVED STATE
_columns (processed)
_rows (processed)"] ``` ### Precedence Rules When the same property is set via multiple sources, higher precedence wins: | Priority | Source | Example | | ----------- | --------------------- | -------------------------------------------- | | 1 (lowest) | `gridConfig` property | `grid.gridConfig = { fitMode: 'stretch' }` | | 2 | Light DOM elements | `` | | 3 | `columns` property | `grid.columns = [{ field: 'name' }]` | | 4 | Inferred columns | (auto-detected from first row) | | 5 (highest) | Individual props | `grid.fitMode = 'fixed'` | > **Note:** HTML attributes (`rows`, `columns`, `grid-config`, `fit-mode`) invoke the corresponding property setters via `attributeChangedCallback` — they are not a separate precedence layer. ### HTML Attribute Configuration The grid supports JSON-serialized configuration via HTML attributes: ```html ``` Supported attributes: `rows`, `columns`, `grid-config`, `fit-mode`. ### Light DOM Configuration The grid parses these light DOM elements on connection: ```html

Custom content here

``` ### Internal State Categories | Category | Example | Description | |----------|---------|-------------| | **Input Properties** | `#rows`, `#columns`, `#gridConfig`, `#fitMode` | Raw user input, stored as-is | | **Effective Config** | `#effectiveConfig` | Merged canonical config — single source of truth | | **Derived State** | `_columns`, `_rows` | Post-plugin-processing state used by rendering | | **Runtime State** | `#hiddenColumns`, `sortState` | User-driven state changes (hide column, sort, etc.) | **Key rule:** Rendering logic reads from `effectiveConfig` or derived state, never from input properties. --- ### Two-Layer Config Architecture ConfigManager implements a two-layer architecture to separate the **original configuration** (from sources) from **runtime mutations**: ```mermaid flowchart TB subgraph sources["SOURCES"] A["gridConfig"] B["columns"] C["fitMode"] D["Light DOM"] E["Shell State Maps"] end A --> F B --> F C --> F D --> F E --> F F["ConfigManager.merge()"] F -->|"sources changed"| G["#originalConfig
(frozen, immutable)"] G -->|"clone"| H["#effectiveConfig
(mutable, runtime changes)"] H -->|"user interaction"| I["Runtime Mutations
hidden, width, sort order"] J["resetState()"] -->|"clone original → effective"| H ``` **Layer 1: Original Config (`#originalConfig`)** - Built from all sources via `#collectAllSources()` - Frozen after creation (`Object.freeze`) - Immutable — never modified after merge - Serves as the "reset point" for the effective config **Layer 2: Effective Config (`#effectiveConfig`)** - Deep cloned from original config - Mutable — runtime changes go here - Column visibility, widths, sort order, etc. - All rendering reads from this layer **Key Behaviors:** | Operation | What Happens | | ----------------------------------------- | ---------------------------------------------------------- | | Source changes (gridConfig, columns, etc.) | `markSourcesChanged()` → `merge()` rebuilds both layers | | Runtime mutation (hide column, resize) | Modify `effectiveConfig` only, `original` untouched | | `resetState()` | Clone `original` → `effective`, discarding runtime changes | | `collectState()` | Diff `effective` vs `original` to get user changes | **When Sources Change:** Sources are re-collected only when `#sourcesChanged` is `true` AND columns already exist: 1. Setting `gridConfig`, `columns`, `fitMode` → auto-marks sources changed 2. Setting Light DOM columns → auto-marks sources changed 3. Shell state updates → call `markSourcesChanged()` explicitly 4. `merge()` is a no-op if sources haven't changed AND columns exist 5. If no columns exist yet, `merge()` always runs (to allow inference from rows) This optimization prevents unnecessary rebuilds when `merge()` is called multiple times per frame. --- ## Rendering Pipeline All rendering flows through a centralized **RenderScheduler** that batches all work into a single `requestAnimationFrame` callback. This eliminates race conditions between different parts of the grid that previously scheduled independent RAFs. ### Render Scheduler Architecture ```mermaid flowchart TB subgraph sources["RENDER REQUESTS"] A["Property Change
(rows, columns, gridConfig)"] B["Framework Adapter
(React/Angular refreshColumns)"] C["ResizeObserver
(container resize)"] D["Scroll Event
(virtualization)"] E["Plugin Request
(afterRender needs)"] end A --> F["RenderScheduler.requestPhase()"] B --> F C --> F D --> G["Direct Call
(hot path)"] E --> F F --> H["Single RAF
#flush()"] H --> I["Phase-Ordered Execution"] subgraph phases["EXECUTION ORDER (data dependencies)"] P1["1. mergeConfig
(FULL/COLUMNS phase)"] P2["2. processRows
(ROWS phase)"] P3["3. processColumns + updateTemplate
(COLUMNS phase)"] P4["4. renderHeader
(HEADER phase)"] P5["5. refreshVirtualWindow
(VIRTUALIZATION phase)"] P6["6. afterRender hooks
(STYLE phase)"] end I --> P1 --> P2 --> P3 --> P4 --> P5 --> P6 ``` ### Render Phases Work is organized into ordered phases. Multiple requests merge to the **highest requested phase**: | Phase | Priority | Work Performed | |-------|----------|----------------| | `STYLE` | 1 | Plugin `afterRender()` hooks only | | `VIRTUALIZATION` | 2 | Recalculate virtual window (+ STYLE) | | `HEADER` | 3 | Re-render header row (+ VIRTUALIZATION) | | `ROWS` | 4 | Rebuild row model (+ HEADER) | | `COLUMNS` | 5 | Process columns, update CSS template (+ ROWS) | | `FULL` | 6 | Merge effective config (+ COLUMNS) | Higher phases implicitly cover all lower phases. Requesting `COLUMNS` when `ROWS` is already pending results in just `COLUMNS` executing. **Example**: If React adapter requests `COLUMNS` and ResizeObserver requests `VIRTUALIZATION` in the same frame, only `COLUMNS` phase runs (which includes all lower phases). ### Execution Order in `#flush()` ```typescript if (phase >= RenderPhase.COLUMNS) mergeConfig(); if (phase >= RenderPhase.ROWS) processRows(); if (phase >= RenderPhase.COLUMNS) processColumns(); if (phase >= RenderPhase.COLUMNS) updateTemplate(); if (phase >= RenderPhase.HEADER) renderHeader(); if (phase >= RenderPhase.VIRTUALIZATION) renderVirtualWindow(); if (phase >= RenderPhase.STYLE) afterRender(); ``` ### Intentional Bypasses Some operations intentionally bypass the scheduler for performance: | Operation | Reason | | ---------------------- | ------------------------------------------ | | Scroll rendering | Hot path — must be synchronous for 60fps | | Shell rebuild | Creates DOM structure, not content updates | | Row height measurement | One-time post-paint measurement | ### Debugging Renders The scheduler is held on a private field (`#scheduler`), so direct introspection from the console is not part of the public API. To trace render activity: - Use the browser **Performance** tab and record around the interaction — each `requestAnimationFrame` callback shows up with the phase work (`processRows`, `processColumns`, `renderHeader`, `renderVirtualWindow`, plugin `afterRender`). - Add `console.log` calls in your own plugin's hooks to confirm which phase fires after a given input. - The `source` argument passed to `requestPhase()` (e.g., `'applyGridConfigUpdate'`, `'resize-observer'`, `'plugin:requestRender'`) is preserved for future debug surfaces; the strings are visible in source files when grepping for `requestPhase(`. --- ## Virtualization ### Row Virtualization (Built-in) The grid maintains a "virtual window" — an offset and count representing which rows are visible: ``` Total rows: 10,000 Viewport: 400px, rowHeight: 28px → ~14 visible rows Overscan: 8 rows above + 8 below = 30 DOM rows in pool Scroll position: 5,000px → startIndex: 178 Rendered: rows 170–200 (30 rows in DOM) ``` - **Row pool**: DOM rows are reused, not created/destroyed on scroll - **Transform-based positioning**: Each row uses `transform: translateY()` for GPU-accelerated positioning - **Range-based updates**: Only rows entering/leaving the viewport get updated content For very small datasets (≤8 rows by default), virtualization is bypassed — the overhead isn't worth it. #### Massive datasets and the browser height cap Browsers cap a single element's rendered height at roughly **33.5M px** (Chromium's `2^25`; Firefox/Safari are similar). With the default `rowHeight: 34`, that's hit at about **986,895 rows**. Above the cap, the faux-vscroll spacer would silently truncate, leaving the tail of the dataset unreachable. To support datasets exceeding the cap (e.g. log viewers with 10M+ rows), the grid switches to **fractional scroll mapping**: - The spacer is clamped at `MAX_ELEMENT_HEIGHT_PX` (≈ 33.5M px). - The native `scrollTop` is treated as a position in the clamped spacer space and translated into a **virtual** offset in raw row-content space: ```text virtualScrollTop = scrollTop * (rawContentHeight − viewport) / (spacerHeight − viewport) ``` - `scrollToRow(N)` reverse-maps the row's offset back into the spacer's `scrollTop` so any row in the dataset is reachable programmatically. For datasets below the cap, mapping is identity — pixel-accurate behavior is unchanged. Above the cap, every row remains reachable via the scrollbar, `Ctrl+End`, and `scrollToRow(N)`. Keyboard cell navigation (`ArrowDown`/`ArrowUp`/`Tab`/`PageDown`/`PageUp`) also stays single-row accurate — focus moves by row index and the auto-scroll that keeps the focused cell visible routes through the mapping. The remaining caveat is **direct scroll input** (mouse wheel, scrollbar drag, `Space`/`Shift+Space`): one pixel of `scrollTop` corresponds to many rows above the cap, so a single wheel notch can skip past hundreds of rows. The mapping helpers (`MAX_ELEMENT_HEIGHT_PX`, `computeScrollMapping`, `toVirtualScrollTop`, `fromVirtualScrollTop`) are exported for plugins that maintain their own scroll-driven DOM state. ### Column Virtualization (Plugin) The `ColumnVirtualizationPlugin` applies the same window concept horizontally. Only columns visible in the horizontal scroll position are rendered. --- ## Plugin System & Feature Registry The plugin lifecycle, hooks, manifest schema, validated properties, communication channels, and the feature registry are documented under [Plugin Development → Architecture](/grid/plugin-development/architecture.md). That page also covers tree-shaking, dependency ordering, and the lazy-hook design that keeps the feature API zero-cost when unused. For a step-by-step tutorial on building your own plugin, see the [Authoring Guide](/grid/plugin-development/custom-plugins.md). --- ## Framework Adapter System How React, Angular, and Vue adapters intercept cell rendering, editor creation, config processing, and cell cleanup is documented under [Framework Adapters → Architecture](/grid/framework-adapters/architecture.md). --- ## Shell System The **shell** is an optional wrapper that adds a header bar, toolbar buttons, and a collapsible tool panel sidebar to the grid. ### Structure ``` ┌──────────────────────────────────────────────────────────┐ │ SHELL HEADER │ │ ┌──────────┬──────────────────┬────────────────────────┐ │ │ │ Title │ Header Content │ Toolbar │ ☰ Toggle │ │ │ └──────────┴──────────────────┴────────────────────────┘ │ ├───────────┬──────────────────────────────────────────────┤ │ TOOL │ │ │ PANEL │ GRID CONTENT │ │ (sidebar) │ │ │ ┌───────┐ │ ┌─────────────────────────────────────┐ │ │ │Section│ │ │ Header Row │ │ │ │ ▼ │ │ ├─────────────────────────────────────┤ │ │ │Content│ │ │ Data Rows (virtualized) │ │ │ │ │ │ │ │ │ │ ├───────┤ │ └─────────────────────────────────────┘ │ │ │Section│ │ │ │ │ ▶ │ │ │ │ └───────┘ │ │ └───────────┴──────────────────────────────────────────────┘ ``` ### Configuration The shell is configured via `gridConfig.shell` or Light DOM elements: ```typescript gridConfig: { shell: { header: { title: 'My Grid' }, toolPanel: { position: 'left' | 'right', // Sidebar position width: '17.5em', // Panel width (CSS value) defaultOpen: 'filters', // Section auto-expanded on first open (v2: also opens sidebar — deprecated, see #259) initialState: 'closed', // 'open' | 'closed' — preferred way to control sidebar open state locked: false, // true = sidebar always open, toggle hidden closeOnClickOutside: false, }, }, } ``` Or declaratively: ```html

Custom center content

``` ### Content Types Plugins and application code can register three types of content: | Type | Location | Example | |------|----------|---------| | **ToolPanel** | Accordion sections in sidebar | Filter panel, visibility panel, pivot config | | **HeaderContent** | Center of header bar | Search box, breadcrumbs | | **ToolbarContent** | Right side of header (before toggle) | Export button, view switcher | Each content type uses a render function pattern: ```typescript grid.registerToolPanel({ id: 'filters', title: 'Filters', icon: '🔍', render: (container) => { container.innerHTML = '

Filter UI here

'; return () => { /* cleanup */ }; }, }); ``` ### Shell State The shell maintains runtime state for: - **Panel open/close** — `isPanelOpen`, toggled via `openToolPanel()` / `closeToolPanel()` - **Expanded sections** — `expandedSections: Set`, accordion state - **Content registrations** — `toolPanels`, `headerContents`, `toolbarContents` Maps - **Cleanup functions** — Each rendered content can return a cleanup callback, tracked for disposal ### Lazy Rendering Tool panel section content is rendered **lazily** — the `render()` function only executes when the user expands that accordion section for the first time. This avoids expensive initialization for panels the user never opens. --- ## Animation System The grid supports CSS-driven animations for row insert, remove, and update operations. ### Animation Types | Type | Trigger | Default Duration | CSS Variable | |------|---------|-----------------|--------------| | `'insert'` | `insertRow()`, bulk add | 300ms | `--tbw-row-insert-duration` | | `'remove'` | `removeRow()`, bulk delete | 200ms | `--tbw-row-remove-duration` | | `'change'` | `animateRow()`, data update highlight | 500ms | `--tbw-row-change-duration` | ### How It Works Animations use a **CSS attribute hook** pattern: 1. Grid sets `data-animating="insert"` on the row element 2. CSS transitions/keyframes in `grid.css` target `[data-animating="insert"]` 3. After the duration, a `setTimeout` removes the attribute (or the row for `'remove'`) 4. A `Promise` resolves when the animation completes ```typescript // Core mechanism (row-animation.ts) rowEl.setAttribute('data-animating', animationType); const duration = getAnimationDuration(rowEl, animationType); setTimeout(() => { if (animationType !== 'remove') { rowEl.removeAttribute('data-animating'); } onComplete?.(); }, duration); ``` ### Animation Configuration ```typescript gridConfig: { animation: { mode: 'reduced-motion', // Default: respects prefers-reduced-motion duration: 200, // Sets --tbw-animation-duration easing: 'ease-out', // Sets --tbw-animation-easing }, } ``` **`mode` options:** | Value | Behavior | |-------|----------| | `true` / `'on'` | Always animate | | `false` / `'off'` | Never animate | | `'reduced-motion'` | Respect `prefers-reduced-motion` media query (default) | ### Public API ```typescript // Highlight a row after data update await grid.animateRow(5, 'change'); // Highlight by row ID await grid.animateRowById('emp-123', 'change'); // Animate multiple rows const count = await grid.animateRows([0, 2, 5], 'change'); // Insert with auto-animation (default) await grid.insertRow(0, newRow); // Animates await grid.insertRow(0, newRow, false); // No animation // Remove with auto-animation (default) const removed = await grid.removeRow(5); // Animates fade-out const removed = await grid.removeRow(5, false); // Immediate ``` All methods return `Promise`s — `await` ensures the animation completes before proceeding. ### CSS Customization Override animation timing per-type via CSS custom properties: ```css tbw-grid { --tbw-row-change-duration: 800ms; /* Longer highlight */ --tbw-row-insert-duration: 0ms; /* Disable insert animation */ --tbw-row-remove-duration: 150ms; /* Faster fade-out */ --tbw-row-change-color: #fff3cd; /* Yellow highlight */ } --- ## DOM Structure ```html

Name

Age

Alice

``` --- ## Styling Architecture ### CSS Custom Properties All styling uses CSS custom properties for theming. Override defaults to customize: ```css tbw-grid { --tbw-color-bg: #ffffff; --tbw-color-fg: #1a1a1a; --tbw-color-border: #e5e5e5; --tbw-color-header-bg: #f5f5f5; --tbw-row-height: 1.75em; /* ~28px at 16px font */ --tbw-header-height: 1.875em; /* ~30px at 16px font */ --tbw-font-family: system-ui, sans-serif; --tbw-font-size: 1em; } ``` ### Key CSS Architecture - **CSS Nesting**: Styles use `tbw-grid { .data-grid-container { ... } }` for scoping - **Cascade Layers**: `@layer tbw-base, tbw-plugins, tbw-theme` — user styles always win - **Adopted Stylesheets**: Dynamic styles use `document.adoptedStyleSheets` for efficiency — styles survive `replaceChildren()` calls - **`em`-Based Sizing**: Row height, padding, and spacing scale with `font-size` ### Plugin Styles Plugins inject CSS via their `styles` property using adopted stylesheets. They use a layered fallback pattern for flexibility: ```css /* Plugin-specific → Global fallback */ background: var(--tbw-selection-bg, var(--tbw-color-selection)); ``` --- ## Event Flow The grid dispatches `CustomEvent`s for every user-visible action (cell clicks, commits, sort changes, etc.). See the [Events section of the API Reference](/grid/api-reference/#events) for the full list and the auto-generated [`DataGridEventMap`](/grid/api/core/interfaces/datagrideventmap/) for payload types. Internally, plugins communicate through two mechanisms described in the [Plugin Communication](#plugin-communication) section above: the **Event Bus** (async, fire-and-forget) and the **Query System** (sync, request-response). Public `CustomEvent`s are dispatched by the core grid or by individual plugins after their internal processing completes. ### Data Flow Example: Sort ``` User clicks sort header ↓ Header click handler → update sortState ↓ Call processRows() on all plugins (MultiSortPlugin sorts) ↓ _rows updated with sorted order ↓ scheduler.requestPhase(ROWS, 'sort') ↓ requestAnimationFrame ↓ Render: update visible row content from new _rows ``` --- ## Performance ### DOM Optimization | Technique | Benefit | | --- | --- | | **Template Cloning** | 3–4× faster than `createElement` | | **Direct DOM Construction** | Avoids innerHTML parsing overhead | | **DocumentFragment** | Single reflow per row | | **Row Pooling** | Zero allocation during scroll | | **Cached DOM Refs** | Avoid querySelector per scroll | ### Rendering Pipeline | Technique | Benefit | | --- | --- | | **Centralized Scheduler** | Eliminates race conditions | | **Phase-Based Execution** | No duplicate work | | **adoptedStyleSheets** | Runtime CSS injection without child node removal | | **Idle Scheduling** | Faster time-to-interactive | | **Fast-Path Patching** | Skip expensive template logic for plain text | | **Cell Display Cache** | Avoid recomputing during scroll | ### Event Handling | Technique | Benefit | | --- | --- | | **Event Delegation** | Constant memory regardless of rows | | **Pooled Scroll Events** | Zero GC pressure during scroll | | **AbortController Cleanup** | No memory leaks on disconnect | --- ## Directory Structure ``` libs/grid/src/ ├─ index.ts # Main entry (auto-registers element) ├─ public.ts # Public API surface (types, constants) ├─ all.ts # All-in-one bundle with all plugins └─ lib/ ├─ core/ │ ├─ grid.ts # Main component class (~4500 lines) │ ├─ grid.css # Core styles │ ├─ types.ts # Public type definitions │ ├─ constants.ts # DOM class/attribute constants │ ├─ internal/ # Pure helper functions │ │ ├─ columns.ts # Column resolution, sizing │ │ ├─ config-manager.ts # Two-layer config (original + effective) │ │ ├─ dom-builder.ts # Direct DOM construction │ │ ├─ render-scheduler.ts # RAF-based render batching │ │ ├─ rows.ts # Row rendering + cell patching │ │ ├─ row-animation.ts # CSS-driven row animations │ │ ├─ shell.ts # Shell header, toolbar, tool panels │ │ ├─ virtualization.ts # Virtual scroll math │ │ ├─ feature-hook.ts # Lazy bridge to feature registry │ │ └─ ... # More internal helpers │ ├─ plugin/ # Plugin infrastructure │ │ ├─ base-plugin.ts # Abstract base class │ │ └─ plugin-manager.ts # Plugin lifecycle │ └─ styles/ # Core CSS (variables, layers) │ └─ variables.css # CSS custom property defaults ├─ features/ # Feature registry (declarative plugin API) │ ├─ registry.ts # registerFeature(), createPluginsFromFeatures() │ ├─ selection.ts # Side-effect: registers selection feature │ ├─ editing.ts # Side-effect: registers editing feature │ └─ ... # 25 feature modules total └─ plugins/ # Built-in plugins ├─ editing/ # Inline cell editing ├─ filtering/ # Column filters ├─ selection/ # Row/cell/range selection ├─ multi-sort/ # Multi-column sorting └─ ... # 24 plugins total ``` ## See Also - [Custom Plugins](/grid/plugin-development/custom-plugins.md) — Build your own plugins with hooks, events, and queries - [Performance Guide](/grid/guides/performance.md) — Render scheduler tuning, virtualization, idle scheduling - [Plugins Overview](/grid/plugins.md) — Available plugins and their hooks - [Theming Guide](/grid/guides/theming.md) — CSS custom properties, themes, cascade layers - [API Reference](/grid/api-reference.md) — Properties, methods, events, and types --- # API Reference > Complete reference for the component — properties, methods, events, CSS custom properties, keyboard shortcuts, declarative configuration, and accessibility. Complete reference for the `` component API. ## Element Tag ```html ``` The custom element is registered as `tbw-grid` (Toolbox Web Grid). ## Properties ### Core Data Properties | Property | Type | Default | Description | | ------------ | ---------------- | ------- | -------------------------- | | `rows` | `T[]` | `[]` | Array of row data objects | | `columns` | [`ColumnConfig[]`](/grid/api/core/interfaces/columnconfig.md) | `[]` | Column configuration array | | `gridConfig` | [`GridConfig`](/grid/api/core/interfaces/gridconfig.md) | `{}` | Full configuration object | ### Layout Properties | Property | Type | Default | Description | | --------- | ---------------------- | ----------- | ---------------------- | | `fitMode` | `'stretch' \| 'fixed'` | `'stretch'` | Column sizing strategy | ### State Properties | Property | Type | Default | Description | | ------------- | --------------------------- | ------- | ------------------------------------------- | | `loading` | `boolean` | `false` | Grid-level loading state. Customise the indicator via [`gridConfig.loadingRenderer`](/grid/api/core/types/loadingrenderer.md) | | `columnState` | [`GridColumnState[]`](/grid/api/core/interfaces/gridcolumnstate.md) | - | Get/set column widths, order, visibility, sort | ### Read-only Properties | Property | Type | Description | | ------------- | ---------------------------- | ----------------------------- | | `changedRows` | `T[]` | Rows with pending edits (requires EditingPlugin) | | `sortState` | `Map` | Current sort state per column | ## Declarative Configuration The grid supports two forms of declarative HTML configuration: 1. **HTML Attributes** — JSON-serialized values on the `` element itself 2. **Light DOM Elements** — Child elements nested inside `` for more readable markup Both approaches can be combined. Light DOM elements take precedence over JSON attributes for the same configuration (e.g., `` elements override the `columns` attribute). :::note JavaScript property assignment always takes precedence over declarative configuration. Removing an attribute or element does not clear a JS-set value. ::: ### HTML Attributes Attributes on the `` element for simple or programmatically-generated configuration: | Attribute | Maps to Property | Type | Description | | ------------- | ---------------- | ------ | -------------------------- | | `rows` | `rows` | JSON | Row data as JSON array | | `columns` | `columns` | JSON | Column config as JSON array| | `grid-config` | `gridConfig` | JSON | Full config object as JSON | | `fit-mode` | `fitMode` | string | `'stretch'` or `'fixed'` | ```html ``` ### Plugin Host Attributes (`data-*`) Some plugins read their own `data-*` attributes directly from the `` host element when they attach. These are namespaced under `data-` to avoid colliding with the grid's own reactive attributes (`rows`, `columns`, `grid-config`, `fit-mode`, `loading`). They are read **once at attach time** — changing them afterward has no effect (use the JSON `grid-config` attribute or a JS property for reactive updates). | Attribute | Owning plugin | Description | | ---------- | ------------------ | -------------------------------------------------------------------------------------------------- | | `data-src` | [`ServerSidePlugin`](/grid/plugins/server-side.md) | URL to fetch row data from — enables a zero-JS server-fetched grid. See [Server-Side → Declarative `data-src`](/grid/plugins/server-side.md#declarative-data-src-zero-js). | ### Light DOM Elements Child elements inside `` for more readable, template-friendly configuration. Preferred for framework templates (Angular, Vue, etc.) and complex column setups with custom renderers/editors. #### Column Elements ##### `` Define column configuration declaratively. | Attribute | Type | Description | | -------------- | --------- | ---------------------------------------------------------------- | | `field` | `string` | **Required.** Data field key | | `header` | `string` | Column header text | | `type` | `string` | Column type. Built-ins: `'string'`, `'number'`, `'boolean'`, `'date'`, `'select'`. Any custom/plugin-registered type string is also accepted. | | `width` | `string` | Column width (e.g., `"120"`, `"100px"`, `"20%"`) | | `min-width` | `number` | Minimum column width in pixels | | `sortable` | `boolean` | Enable sorting (presence = true) | | `resizable` | `boolean` | Enable resizing (presence = true) | | `order` | `number` | Initial column position (0-based index; must be non-negative integer). Columns without `order` fill positions in declaration order. Only affects initial render; user reorder takes precedence. | | `editable` | `boolean` | Enable editing (presence = true, requires EditingPlugin) | | `options` | `string` | Select options: `"value1:Label1,value2:Label2"` or `"val1,val2"` | | `pinned` | `string` | Pin the column to an edge: `'left'` / `'start'` or `'right'` / `'end'` (requires PinnedColumnsPlugin). | | `hidden` | `boolean` | Hide the column initially (presence = true; `hidden="false"` keeps it visible). Requires VisibilityPlugin. | | `lock-visible` | `boolean` | Prevent the column from being hidden via the visibility panel (presence = true). Requires VisibilityPlugin. | > Plugin-contributed attributes (`pinned`, `hidden`, `lock-visible`, `editable`, ``) are read by their owning plugin when it is registered. They set the column's **initial** state — subsequent runtime changes (e.g. `setColumnVisible()`, drag-to-pin) take precedence. ```html

``` ##### `` Custom view template inside a column. Content is used as the cell renderer. ```html

``` ##### `` Custom editor template inside a column (requires EditingPlugin). ```html

``` ##### `` Custom header template inside a column. ```html

Status *

``` #### Shell Elements ##### `` Configure the shell header bar. | Attribute | Type | Description | | --------- | -------- | ------------------------ | | `title` | `string` | Grid title (left side) | ```html

20 employees

``` ##### `` Custom content in the shell header center area. Must be nested inside ``. ```html

``` ##### `` Container for toolbar buttons (right side of shell header). ```html

``` #### Tool Panel Elements ##### `` Define a custom tool panel for the sidebar. | Attribute | Type | Description | | --------- | -------- | ---------------------------------------------- | | `id` | `string` | **Required.** Unique panel identifier | | `title` | `string` | **Required.** Panel title in accordion header | | `icon` | `string` | Icon for accordion header (emoji or text) | | `tooltip` | `string` | Tooltip for accordion header | | `order` | `number` | Panel order priority (lower = first, default: 100) | ```html

``` #### Plugin-Specific Elements ##### `` (MasterDetailPlugin) Define the detail panel template for master-detail rows. Requires the MasterDetailPlugin. | Attribute | Type | Description | | --------------------- | ----------------------------- | ---------------------------------------------------- | | `animation` | `'slide' \| 'fade' \| false` | Panel expand/collapse animation (default: `'slide'`) | | `show-expand-column` | `boolean` | Show expand/collapse column (default: `true`) | | `expand-on-row-click` | `boolean` | Expand when row clicked (default: `false`) | | `height` | `number \| 'auto'` | Panel height in pixels or auto (default: `'auto'`) | ```html

``` See the [MasterDetailPlugin documentation](/grid/plugins/master-detail.md) for more details. ##### `` (ResponsivePlugin) Define a custom card template for responsive mode. Requires the ResponsivePlugin. | Attribute | Type | Description | | ----------------- | -------------------- | ------------------------------------------------------- | | `breakpoint` | `number` | Width threshold in pixels for responsive mode | | `card-row-height` | `number \| 'auto'` | Card height in pixels or auto (default: `'auto'`) | | `hidden-columns` | `string` | Comma-separated field names to hide in card mode | | `hide-header` | `boolean` | Hide header row in responsive mode (default: `true`) | | `debounce-ms` | `number` | Resize debounce delay in ms (default: `100`) | ```html

{{ row.name }} {{ row.email }}

``` See the [ResponsivePlugin documentation](/grid/plugins/responsive.md) for more details. :::note Framework adapters may provide wrapper components for these elements. For example, `@toolbox-web/grid-react` provides `` and `` React components with render prop support. See the [React adapter docs](/grid/react/getting-started.md) for details. ::: ## Helper Functions ```typescript import { createGrid, queryGrid } from '@toolbox-web/grid'; // Create a new grid element with configuration const grid = createGrid({ columns: [{ field: 'name' }, { field: 'email' }], fitMode: 'stretch', }); document.body.appendChild(grid); grid.rows = employees; // Query an existing grid with type safety const existingGrid = queryGrid('#my-grid'); if (existingGrid) { existingGrid.rows = newData; } ``` ## Methods ### Data Methods ```typescript // Update row data grid.rows = newData; // Wait for grid to be ready await grid.ready(); // Force layout recalculation await grid.forceLayout(); // Get current configuration (readonly) const config = await grid.getConfig(); ``` ### Row Update API The Row Update API provides ID-based access to individual rows for reading and updating data. This is especially useful when you need to update rows after external changes (e.g., API responses, WebSocket events) without replacing the entire dataset. #### Row Identification The grid automatically determines row IDs using these sources (in order of precedence): 1. `getRowId` function in gridConfig (custom ID resolution) 2. `id` property on the row object 3. `_id` property on the row object :::note Rows without any of these will not be accessible via the Row Update API. Calls to `getRow()` or `updateRow()` for such rows will return `undefined` or have no effect. ::: ```typescript // Configure custom row ID resolution grid.gridConfig = { columns: [...], getRowId: (row) => row.employeeId, // Use a custom field as ID }; // Get a row's ID const id = grid.getRowId(row); console.log(id); // "EMP-123" ``` #### Reading Rows ```typescript // Get a single row by its ID const employee = grid.getRow('EMP-123'); if (employee) { console.log(employee.name); } // Returns undefined if the row is not found const missing = grid.getRow('unknown-id'); console.log(missing); // undefined ``` #### Updating Rows ```typescript // Update a single row by ID grid.updateRow('EMP-123', { status: 'active', salary: 75000 }); // Batch update multiple rows grid.updateRows([ { id: 'EMP-123', changes: { status: 'active' } }, { id: 'EMP-456', changes: { department: 'Engineering' } }, ]); // Specify the update source (default: 'api') // Valid sources: 'user' | 'cascade' | 'api' grid.updateRow('EMP-123', { status: 'inactive' }, 'api'); grid.updateRows(updates, 'api'); ``` #### Listening to Row Updates The `cell-change` event fires whenever row data is updated via the Row Update API: ```typescript grid.on('cell-change', ({ rowId, changes, source, row }) => { console.log(`Row ${rowId} updated via ${source}:`); console.log('Changes:', changes); // { status: 'active' } console.log('Full row:', row); // Complete row object after update }); ``` :::note The `cell-change` event is distinct from `cell-commit`, which fires during inline editing. Use `cell-change` for programmatic updates via `updateRow()`/`updateRows()`. ::: ### Column Methods ```typescript // Get all columns with visibility info const columns = grid.getAllColumns(); // Returns: Array<{ field, header, visible, lockVisible? }> // Show/hide columns grid.setColumnVisible('fieldName', false); grid.toggleColumnVisibility('fieldName'); grid.showAllColumns(); // Check column visibility const isVisible = grid.isColumnVisible('fieldName'); // Reorder columns grid.setColumnOrder(['id', 'name', 'email']); const order = grid.getColumnOrder(); ``` ### Editing Methods Bulk-edit lifecycle, change tracking, and active-row controls are provided by the **Editing plugin** and surfaced on the grid instance when the plugin is loaded. See [Editing Plugin → Imperative Bulk-Edit API](/grid/plugins/editing.md#imperative-bulk-edit-api) for the full method list and examples. ### Plugin Methods | Method | Returns | Description | | ------------------------ | ------------------------------ | ------------------------------------------------------ | | `getPluginByName(name)` | `Plugin \| undefined` | Get plugin instance by name — **preferred** (type-safe, no import needed) | | `getPlugin(PluginClass)` | `P \| undefined` | Get plugin instance by class (requires import) | `getPluginByName` is type-safe for all built-in plugins via the `PluginNameMap` interface — TypeScript automatically returns the correct plugin type (e.g., `SelectionPlugin` for `'selection'`). ```typescript // Preferred — type-safe, no import needed const selection = grid.getPluginByName('selection'); selection?.selectAll(); // ✅ SelectionPlugin methods are available // Alternative — get by class (requires plugin import) import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection'; const sel = grid.getPlugin(SelectionPlugin); // Check if plugin is registered if (selection) { selection.selectAll(); } ``` ### Custom Styles API The grid uses **light DOM** — standard CSS targeting elements inside `` works normally (global stylesheets, `