@toolbox-web/grid 0.0.1

package/index.d.ts

@@ -0,0 +1,2367 @@
+/** Fired when keyboard navigation or programmatic focus changes active cell. */
+export declare interface ActivateCellDetail {
+    /** Zero-based row index now focused. */
+    row: number;
+    /** Zero-based column index now focused. */
+    col: number;
+}
+
+/**
+ * Aggregators Core Registry
+ *
+ * Provides a central registry for aggregator functions.
+ * Built-in aggregators are provided by default.
+ * Plugins can register additional aggregators.
+ *
+ * The registry is exposed as a singleton object that can be accessed:
+ * - By ES module imports: import { aggregatorRegistry } from '@toolbox-web/grid'
+ * - By UMD/CDN: TbwGrid.aggregatorRegistry
+ * - By plugins via context: ctx.aggregatorRegistry
+ */
+export declare type AggregatorFn = (rows: any[], field: string, column?: any) => any;
+
+/** Map of field names to aggregator references */
+declare type AggregatorMap = Record<string, AggregatorRef_2>;
+
+export declare type AggregatorRef = string | ((rows: any[], field: string, column?: any) => any);
+
+declare type AggregatorRef_2 = string | AggregatorFn;
+
+/**
+ * The aggregator registry singleton.
+ * Plugins should access this through context or the global namespace.
+ */
+export declare const aggregatorRegistry: {
+    /**
+     * Register a custom aggregator function.
+     */
+    register(name: string, fn: AggregatorFn): void;
+    /**
+     * Unregister a custom aggregator function.
+     */
+    unregister(name: string): void;
+    /**
+     * Get an aggregator function by reference.
+     */
+    get(ref: AggregatorRef_2 | undefined): AggregatorFn | undefined;
+    /**
+     * Run an aggregator on a set of rows.
+     */
+    run(ref: AggregatorRef_2 | undefined, rows: any[], field: string, column?: any): any;
+    /**
+     * Check if an aggregator exists.
+     */
+    has(name: string): boolean;
+    /**
+     * List all available aggregator names.
+     */
+    list(): string[];
+};
+
+/**
+ * Base contract for a column. Public; kept intentionally lean so host apps can extend via intersection types.
+ * Prefer adding optional properties here only when broadly useful to most grids.
+ */
+export declare interface BaseColumnConfig<TRow = any, TValue = any> {
+    /** Unique field key referencing property in row objects */
+    field: keyof TRow & string;
+    /** Visible header label; defaults to capitalized field */
+    header?: string;
+    /** Column data type; inferred if omitted */
+    type?: PrimitiveColumnType;
+    /** Column width in pixels; fixed size (no flexibility) */
+    width?: string | number;
+    /** Minimum column width in pixels (stretch mode only); when set, column uses minmax(minWidth, 1fr) */
+    minWidth?: number;
+    /** Whether column can be sorted */
+    sortable?: boolean;
+    /** Whether column can be resized by user */
+    resizable?: boolean;
+    /** Optional custom comparator for sorting (a,b) -> number */
+    sortComparator?: (a: TValue, b: TValue, rowA: TRow, rowB: TRow) => number;
+    /** Whether the field is editable (enables editors) */
+    editable?: boolean;
+    /** Optional custom editor factory or element tag name */
+    editor?: ColumnEditorSpec<TRow, TValue>;
+    /** For select/typeahead types - available options */
+    options?: Array<{
+        label: string;
+        value: any;
+    }> | (() => Array<{
+        label: string;
+        value: any;
+    }>);
+    /** For select/typeahead - allow multi select */
+    multi?: boolean;
+    /** Optional formatter */
+    format?: (value: TValue, row: TRow) => string;
+    /** Arbitrary extra metadata */
+    meta?: Record<string, any>;
+}
+
+/**
+ * Abstract base class for all grid plugins.
+ *
+ * @template TConfig - Configuration type for the plugin
+ */
+export declare abstract class BaseGridPlugin<TConfig = unknown> {
+    /** Unique plugin identifier (derived from class name by default) */
+    abstract readonly name: string;
+    /** Plugin version - override in subclass if needed */
+    readonly version: string;
+    /** CSS styles to inject into the grid's shadow DOM */
+    readonly styles?: string;
+    /** Custom cell renderers keyed by type name */
+    readonly cellRenderers?: Record<string, CellRenderer>;
+    /** Custom header renderers keyed by type name */
+    readonly headerRenderers?: Record<string, HeaderRenderer>;
+    /** Custom cell editors keyed by type name */
+    readonly cellEditors?: Record<string, CellEditor>;
+    /** The grid instance this plugin is attached to */
+    protected grid: GridElement;
+    /** Plugin configuration - merged with defaults in attach() */
+    protected config: TConfig;
+    /** User-provided configuration from constructor */
+    private readonly userConfig;
+    /**
+     * Default configuration - subclasses should override this getter.
+     * Note: This must be a getter (not property initializer) for proper inheritance
+     * since property initializers run after parent constructor.
+     */
+    protected get defaultConfig(): Partial<TConfig>;
+    constructor(config?: Partial<TConfig>);
+    /**
+     * Called when the plugin is attached to a grid.
+     * Override to set up event listeners, initialize state, etc.
+     */
+    attach(grid: GridElement): void;
+    /**
+     * Called when the plugin is detached from a grid.
+     * Override to clean up event listeners, timers, etc.
+     */
+    detach(): void;
+    /**
+     * Get another plugin instance from the same grid.
+     * Use for inter-plugin communication.
+     */
+    protected getPlugin<T extends BaseGridPlugin>(PluginClass: new (...args: any[]) => T): T | undefined;
+    /**
+     * Emit a custom event from the grid.
+     */
+    protected emit<T>(eventName: string, detail: T): void;
+    /**
+     * Request a re-render of the grid.
+     */
+    protected requestRender(): void;
+    /**
+     * Request a lightweight style update without rebuilding DOM.
+     * Use this instead of requestRender() when only CSS classes need updating.
+     */
+    protected requestAfterRender(): void;
+    /**
+     * Get the current rows from the grid.
+     */
+    protected get rows(): any[];
+    /**
+     * Get the original unfiltered/unprocessed rows from the grid.
+     * Use this when you need all source data regardless of active filters.
+     */
+    protected get sourceRows(): any[];
+    /**
+     * Get the current columns from the grid.
+     */
+    protected get columns(): ColumnConfig[];
+    /**
+     * Get only visible columns from the grid (excludes hidden).
+     * Use this for rendering that needs to match the grid template.
+     */
+    protected get visibleColumns(): ColumnConfig[];
+    /**
+     * Get the shadow root of the grid.
+     */
+    protected get shadowRoot(): ShadowRoot | null;
+    /**
+     * Log a warning message.
+     */
+    protected warn(message: string): void;
+    /**
+     * Transform rows before rendering.
+     * Called during each render cycle before rows are rendered to the DOM.
+     * Use this to filter, sort, or add computed properties to rows.
+     *
+     * @param rows - The current rows array (readonly to encourage returning a new array)
+     * @returns The modified rows array to render
+     *
+     * @example
+     * ```ts
+     * processRows(rows: readonly any[]): any[] {
+     *   // Filter out hidden rows
+     *   return rows.filter(row => !row._hidden);
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * processRows(rows: readonly any[]): any[] {
+     *   // Add computed properties
+     *   return rows.map(row => ({
+     *     ...row,
+     *     _fullName: `${row.firstName} ${row.lastName}`
+     *   }));
+     * }
+     * ```
+     */
+    processRows?(rows: readonly any[]): any[];
+    /**
+     * Transform columns before rendering.
+     * Called during each render cycle before column headers and cells are rendered.
+     * Use this to add, remove, or modify column definitions.
+     *
+     * @param columns - The current columns array (readonly to encourage returning a new array)
+     * @returns The modified columns array to render
+     *
+     * @example
+     * ```ts
+     * processColumns(columns: readonly ColumnConfig[]): ColumnConfig[] {
+     *   // Add a selection checkbox column
+     *   return [
+     *     { field: '_select', header: '', width: 40 },
+     *     ...columns
+     *   ];
+     * }
+     * ```
+     */
+    processColumns?(columns: readonly ColumnConfig[]): ColumnConfig[];
+    /**
+     * Called before each render cycle begins.
+     * Use this to prepare state or cache values needed during rendering.
+     *
+     * @example
+     * ```ts
+     * beforeRender(): void {
+     *   this.visibleRowCount = this.calculateVisibleRows();
+     * }
+     * ```
+     */
+    beforeRender?(): void;
+    /**
+     * Called after each render cycle completes.
+     * Use this for DOM manipulation, adding event listeners to rendered elements,
+     * or applying visual effects like selection highlights.
+     *
+     * @example
+     * ```ts
+     * afterRender(): void {
+     *   // Apply selection styling to rendered rows
+     *   const rows = this.shadowRoot?.querySelectorAll('.data-row');
+     *   rows?.forEach((row, i) => {
+     *     row.classList.toggle('selected', this.selectedRows.has(i));
+     *   });
+     * }
+     * ```
+     */
+    afterRender?(): void;
+    /**
+     * Render a custom row, bypassing the default row rendering.
+     * Use this for special row types like group headers, detail rows, or footers.
+     *
+     * @param row - The row data object
+     * @param rowEl - The row DOM element to render into
+     * @param rowIndex - The index of the row in the data array
+     * @returns `true` if the plugin handled rendering (prevents default), `false`/`void` for default rendering
+     *
+     * @example
+     * ```ts
+     * renderRow(row: any, rowEl: HTMLElement, rowIndex: number): boolean | void {
+     *   if (row._isGroupHeader) {
+     *     rowEl.innerHTML = `<div class="group-header">${row._groupLabel}</div>`;
+     *     return true; // Handled - skip default rendering
+     *   }
+     *   // Return void to let default rendering proceed
+     * }
+     * ```
+     */
+    renderRow?(row: any, rowEl: HTMLElement, rowIndex: number): boolean | void;
+    /**
+     * Handle keyboard events on the grid.
+     * Called when a key is pressed while the grid or a cell has focus.
+     *
+     * @param event - The native KeyboardEvent
+     * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default
+     *
+     * @example
+     * ```ts
+     * onKeyDown(event: KeyboardEvent): boolean | void {
+     *   // Handle Ctrl+A for select all
+     *   if (event.ctrlKey && event.key === 'a') {
+     *     this.selectAllRows();
+     *     return true; // Prevent default browser select-all
+     *   }
+     * }
+     * ```
+     */
+    onKeyDown?(event: KeyboardEvent): boolean | void;
+    /**
+     * Handle cell click events.
+     * Called when a data cell is clicked (not headers).
+     *
+     * @param event - Cell click event with row/column context
+     * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default
+     *
+     * @example
+     * ```ts
+     * onCellClick(event: CellClickEvent): boolean | void {
+     *   if (event.field === '_select') {
+     *     this.toggleRowSelection(event.rowIndex);
+     *     return true; // Handled
+     *   }
+     * }
+     * ```
+     */
+    onCellClick?(event: CellClickEvent): boolean | void;
+    /**
+     * Handle row click events.
+     * Called when any part of a data row is clicked.
+     * Note: This is called in addition to onCellClick, not instead of.
+     *
+     * @param event - Row click event with row context
+     * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default
+     *
+     * @example
+     * ```ts
+     * onRowClick(event: RowClickEvent): boolean | void {
+     *   if (this.config.mode === 'row') {
+     *     this.selectRow(event.rowIndex, event.originalEvent);
+     *     return true;
+     *   }
+     * }
+     * ```
+     */
+    onRowClick?(event: RowClickEvent): boolean | void;
+    /**
+     * Handle header click events.
+     * Called when a column header is clicked. Commonly used for sorting.
+     *
+     * @param event - Header click event with column context
+     * @returns `true` to prevent default behavior and stop propagation, `false`/`void` to allow default
+     *
+     * @example
+     * ```ts
+     * onHeaderClick(event: HeaderClickEvent): boolean | void {
+     *   if (event.column.sortable !== false) {
+     *     this.toggleSort(event.field);
+     *     return true;
+     *   }
+     * }
+     * ```
+     */
+    onHeaderClick?(event: HeaderClickEvent): boolean | void;
+    /**
+     * Handle scroll events on the grid viewport.
+     * Called during scrolling. Note: This may be called frequently; debounce if needed.
+     *
+     * @param event - Scroll event with scroll position and viewport dimensions
+     *
+     * @example
+     * ```ts
+     * onScroll(event: ScrollEvent): void {
+     *   // Update sticky column positions
+     *   this.updateStickyPositions(event.scrollLeft);
+     * }
+     * ```
+     */
+    onScroll?(event: ScrollEvent): void;
+    /**
+     * Handle cell mousedown events.
+     * Used for initiating drag operations like range selection or column resize.
+     *
+     * @param event - Mouse event with cell context
+     * @returns `true` to indicate drag started (prevents text selection), `false`/`void` otherwise
+     *
+     * @example
+     * ```ts
+     * onCellMouseDown(event: CellMouseEvent): boolean | void {
+     *   if (event.rowIndex !== undefined && this.config.mode === 'range') {
+     *     this.startDragSelection(event.rowIndex, event.colIndex);
+     *     return true; // Prevent text selection
+     *   }
+     * }
+     * ```
+     */
+    onCellMouseDown?(event: CellMouseEvent): boolean | void;
+    /**
+     * Handle cell mousemove events during drag operations.
+     * Only called when a drag is in progress (after mousedown returned true).
+     *
+     * @param event - Mouse event with current cell context
+     * @returns `true` to continue handling the drag, `false`/`void` otherwise
+     *
+     * @example
+     * ```ts
+     * onCellMouseMove(event: CellMouseEvent): boolean | void {
+     *   if (this.isDragging && event.rowIndex !== undefined) {
+     *     this.extendSelection(event.rowIndex, event.colIndex);
+     *     return true;
+     *   }
+     * }
+     * ```
+     */
+    onCellMouseMove?(event: CellMouseEvent): boolean | void;
+    /**
+     * Handle cell mouseup events to end drag operations.
+     *
+     * @param event - Mouse event with final cell context
+     * @returns `true` if drag was finalized, `false`/`void` otherwise
+     *
+     * @example
+     * ```ts
+     * onCellMouseUp(event: CellMouseEvent): boolean | void {
+     *   if (this.isDragging) {
+     *     this.finalizeDragSelection();
+     *     this.isDragging = false;
+     *     return true;
+     *   }
+     * }
+     * ```
+     */
+    onCellMouseUp?(event: CellMouseEvent): boolean | void;
+    /**
+     * Provide context menu items when right-clicking on the grid.
+     * Multiple plugins can contribute items; they are merged into a single menu.
+     *
+     * @param params - Context about where the menu was triggered (row, column, etc.)
+     * @returns Array of menu items to display
+     *
+     * @example
+     * ```ts
+     * getContextMenuItems(params: ContextMenuParams): ContextMenuItem[] {
+     *   if (params.isHeader) {
+     *     return [
+     *       { id: 'sort-asc', label: 'Sort Ascending', action: () => this.sortAsc(params.field) },
+     *       { id: 'sort-desc', label: 'Sort Descending', action: () => this.sortDesc(params.field) },
+     *     ];
+     *   }
+     *   return [
+     *     { id: 'copy', label: 'Copy Cell', action: () => this.copyCell(params) },
+     *   ];
+     * }
+     * ```
+     */
+    getContextMenuItems?(params: ContextMenuParams): ContextMenuItem[];
+    /**
+     * Contribute plugin-specific state for a column.
+     * Called by the grid when collecting column state for serialization.
+     * Plugins can add their own properties to the column state.
+     *
+     * @param field - The field name of the column
+     * @returns Partial column state with plugin-specific properties, or undefined if no state to contribute
+     *
+     * @example
+     * ```ts
+     * getColumnState(field: string): Partial<ColumnState> | undefined {
+     *   const filterModel = this.filterModels.get(field);
+     *   if (filterModel) {
+     *     // Uses module augmentation to add filter property to ColumnState
+     *     return { filter: filterModel } as Partial<ColumnState>;
+     *   }
+     *   return undefined;
+     * }
+     * ```
+     */
+    getColumnState?(field: string): Partial<ColumnState> | undefined;
+    /**
+     * Apply plugin-specific state to a column.
+     * Called by the grid when restoring column state from serialized data.
+     * Plugins should restore their internal state based on the provided state.
+     *
+     * @param field - The field name of the column
+     * @param state - The column state to apply (may contain plugin-specific properties)
+     *
+     * @example
+     * ```ts
+     * applyColumnState(field: string, state: ColumnState): void {
+     *   // Check for filter property added via module augmentation
+     *   const filter = (state as any).filter;
+     *   if (filter) {
+     *     this.filterModels.set(field, filter);
+     *     this.applyFilter();
+     *   }
+     * }
+     * ```
+     */
+    applyColumnState?(field: string, state: ColumnState): void;
+    /**
+     * Register a tool panel for this plugin.
+     * Return undefined if plugin has no tool panel.
+     * The shell will create a toolbar toggle button and render the panel content
+     * when the user opens the panel.
+     *
+     * @returns Tool panel definition, or undefined if plugin has no panel
+     *
+     * @example
+     * ```ts
+     * getToolPanel(): ToolPanelDefinition | undefined {
+     *   return {
+     *     id: 'columns',
+     *     title: 'Columns',
+     *     icon: '☰',
+     *     tooltip: 'Show/hide columns',
+     *     order: 10,
+     *     render: (container) => {
+     *       this.renderColumnList(container);
+     *       return () => this.cleanup();
+     *     },
+     *   };
+     * }
+     * ```
+     */
+    getToolPanel?(): ToolPanelDefinition | undefined;
+    /**
+     * Register content for the shell header center section.
+     * Return undefined if plugin has no header content.
+     * Examples: search input, selection summary, status indicators.
+     *
+     * @returns Header content definition, or undefined if plugin has no header content
+     *
+     * @example
+     * ```ts
+     * getHeaderContent(): HeaderContentDefinition | undefined {
+     *   return {
+     *     id: 'quick-filter',
+     *     order: 10,
+     *     render: (container) => {
+     *       const input = document.createElement('input');
+     *       input.type = 'text';
+     *       input.placeholder = 'Search...';
+     *       input.addEventListener('input', this.handleInput);
+     *       container.appendChild(input);
+     *       return () => input.removeEventListener('input', this.handleInput);
+     *     },
+     *   };
+     * }
+     * ```
+     */
+    getHeaderContent?(): HeaderContentDefinition | undefined;
+}
+
+/**
+ * Cell click event
+ */
+export declare interface CellClickEvent {
+    rowIndex: number;
+    colIndex: number;
+    field: string;
+    value: any;
+    row: any;
+    cellEl: HTMLElement;
+    originalEvent: MouseEvent;
+}
+
+export declare interface CellCommitDetail<TRow = any> {
+    /** The mutated row after commit. */
+    row: TRow;
+    /** Field name whose value changed. */
+    field: string;
+    /** New value stored. */
+    value: any;
+    /** Index of the row in current data set. */
+    rowIndex: number;
+    /** All rows that have at least one committed change (snapshot list). */
+    changedRows: TRow[];
+    /** Indices parallel to changedRows. */
+    changedRowIndices: number[];
+    /** True if this row just entered the changed set. */
+    firstTimeForRow: boolean;
+}
+
+/**
+ * Runtime cell context used internally for compiled template execution.
+ */
+declare interface CellContext<T = any> {
+    row: T;
+    value: any;
+    field: string;
+    column: ColumnInternal<T>;
+}
+
+/**
+ * Cell coordinates
+ */
+export declare interface CellCoords {
+    row: number;
+    col: number;
+}
+
+/**
+ * Cell editor interface for plugins.
+ */
+export declare interface CellEditor {
+    create(ctx: PluginCellRenderContext, commitFn: (value: any) => void, cancelFn: () => void): HTMLElement;
+    getValue?(element: HTMLElement): any;
+    focus?(element: HTMLElement): void;
+}
+
+/**
+ * Cell mouse event (for drag operations, selection, etc.)
+ */
+export declare interface CellMouseEvent {
+    /** Event type: mousedown, mousemove, or mouseup */
+    type: 'mousedown' | 'mousemove' | 'mouseup';
+    /** Row index, undefined if not over a data cell */
+    rowIndex?: number;
+    /** Column index, undefined if not over a cell */
+    colIndex?: number;
+    /** Field name, undefined if not over a cell */
+    field?: string;
+    /** Cell value, undefined if not over a data cell */
+    value?: unknown;
+    /** Row data object, undefined if not over a data row */
+    row?: unknown;
+    /** Column configuration, undefined if not over a column */
+    column?: ColumnConfig;
+    /** The cell element, undefined if not over a cell */
+    cellElement?: HTMLElement;
+    /** The row element, undefined if not over a row */
+    rowElement?: HTMLElement;
+    /** Whether the event is over a header cell */
+    isHeader: boolean;
+    /** Cell coordinates if over a valid data cell */
+    cell?: CellCoords;
+    /** The original mouse event */
+    originalEvent: MouseEvent;
+}
+
+/** Public representation of a cell range (for events) */
+export declare interface CellRange {
+    /** Starting cell coordinates */
+    from: {
+        row: number;
+        col: number;
+    };
+    /** Ending cell coordinates */
+    to: {
+        row: number;
+        col: number;
+    };
+}
+
+/**
+ * Context passed to custom view renderers (pure display – no commit helpers).
+ */
+export declare interface CellRenderContext<TRow = any, TValue = any> {
+    /** Row object for the cell being rendered. */
+    row: TRow;
+    /** Value at field. */
+    value: TValue;
+    /** Field key. */
+    field: keyof TRow & string;
+    /** Column configuration reference. */
+    column: ColumnConfig<TRow>;
+}
+
+/**
+ * Cell renderer function type for plugins.
+ */
+export declare type CellRenderer = (ctx: PluginCellRenderContext) => string | HTMLElement;
+
+/** Emitted when the changed rows tracking set is cleared programmatically. */
+export declare interface ChangedRowsResetDetail<TRow = any> {
+    /** New (empty) changed rows array after reset. */
+    rows: TRow[];
+    /** Parallel indices (likely empty). */
+    indices: number[];
+}
+
+/**
+ * Full column configuration including optional custom view/renderer & grouping metadata.
+ */
+export declare interface ColumnConfig<TRow = any> extends BaseColumnConfig<TRow, any> {
+    /** Optional custom view renderer used instead of default text rendering */
+    viewRenderer?: ColumnViewRenderer<TRow, any>;
+    /** External view spec (lets host app mount any framework component) */
+    externalView?: {
+        component: any;
+        props?: Record<string, any>;
+        mount?: (options: {
+            placeholder: HTMLElement;
+            context: CellRenderContext<TRow, any>;
+            spec: any;
+        }) => void | {
+            dispose?: () => void;
+        };
+    };
+    /** Whether the column is initially hidden */
+    hidden?: boolean;
+    /** Prevent this column from being hidden by the visibility plugin */
+    lockVisible?: boolean;
+}
+
+export declare type ColumnConfigMap<TRow = any> = ColumnConfig<TRow>[];
+
+/**
+ * Context object provided to editor factories allowing mutation (commit/cancel) of a cell value.
+ */
+export declare interface ColumnEditorContext<TRow = any, TValue = any> {
+    /** Underlying full row object for the active edit. */
+    row: TRow;
+    /** Current cell value (mutable only via commit). */
+    value: TValue;
+    /** Field name being edited. */
+    field: keyof TRow & string;
+    /** Column configuration reference. */
+    column: ColumnConfig<TRow>;
+    /** Accept the edit; triggers change tracking + rerender. */
+    commit: (newValue: TValue) => void;
+    /** Abort edit without persisting changes. */
+    cancel: () => void;
+}
+
+/** External editor spec: tag name, factory function, or external mount spec */
+export declare type ColumnEditorSpec<TRow = any, TValue = any> = string | ((context: ColumnEditorContext<TRow, TValue>) => HTMLElement | string) | {
+    /** Arbitrary component reference (class, function, token) */
+    component: any;
+    /** Optional static props passed to mount */
+    props?: Record<string, any>;
+    /** Optional custom mount function; if provided we call it directly instead of emitting an event */
+    mount?: (options: {
+        placeholder: HTMLElement;
+        context: ColumnEditorContext<TRow, TValue>;
+        spec: any;
+    }) => void | {
+        dispose?: () => void;
+    };
+};
+
+declare interface ColumnInternal<T = any> extends ColumnConfig<T> {
+    __autoSized?: boolean;
+    __userResized?: boolean;
+    __renderedWidth?: number;
+    __viewTemplate?: HTMLElement;
+    __editorTemplate?: HTMLElement;
+    __headerTemplate?: HTMLElement;
+    __compiledView?: (ctx: CellContext<T>) => string;
+    __compiledEditor?: (ctx: EditorExecContext<T>) => string;
+}
+
+/** Column resize event detail containing final pixel width. */
+export declare interface ColumnResizeDetail {
+    /** Resized column field key. */
+    field: string;
+    /** New width in pixels. */
+    width: number;
+}
+
+/**
+ * Sort state for a column
+ */
+export declare interface ColumnSortState {
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+    /** Priority for multi-sort (0 = primary, 1 = secondary, etc.) */
+    priority: number;
+}
+
+/**
+ * State for a single column. Captures user-driven changes at runtime.
+ * Plugins can extend this interface via module augmentation to add their own state.
+ *
+ * @example
+ * ```ts
+ * // In filtering plugin
+ * declare module '@toolbox-web/grid' {
+ *   interface ColumnState {
+ *     filter?: FilterValue;
+ *   }
+ * }
+ * ```
+ */
+export declare interface ColumnState {
+    /** Column field identifier */
+    field: string;
+    /** Position index after reordering (0-based) */
+    order: number;
+    /** Width in pixels (undefined = use default) */
+    width?: number;
+    /** Visibility state */
+    visible: boolean;
+    /** Sort state (undefined = not sorted) */
+    sort?: ColumnSortState;
+}
+
+export declare type ColumnViewRenderer<TRow = any, TValue = any> = (ctx: CellRenderContext<TRow, TValue>) => Node | string | void;
+
+/**
+ * Context menu item
+ */
+export declare interface ContextMenuItem {
+    id: string;
+    label: string;
+    icon?: string;
+    disabled?: boolean;
+    separator?: boolean;
+    children?: ContextMenuItem[];
+    action?: (params: ContextMenuParams) => void;
+}
+
+/**
+ * Context menu parameters
+ */
+export declare interface ContextMenuParams {
+    x: number;
+    y: number;
+    rowIndex?: number;
+    colIndex?: number;
+    field?: string;
+    value?: any;
+    row?: any;
+    column?: ColumnConfig;
+    isHeader?: boolean;
+}
+
+export declare type DataGridCustomEvent<K extends keyof DataGridEventMap<any>, TRow = any> = CustomEvent<DataGridEventMap<TRow>[K]>;
+
+/**
+ * High-performance data grid web component.
+ * During migration, uses tbw-grid tag to avoid conflicts with existing datagrid.
+ * Will be renamed back to data-grid when migration is complete.
+ *
+ * ## Configuration Architecture
+ *
+ * The grid follows a **single source of truth** pattern where all configuration
+ * converges into `#effectiveConfig`. Users can set configuration via multiple inputs:
+ *
+ * **Input Sources (precedence low → high):**
+ * 1. `gridConfig` property - base configuration object
+ * 2. Light DOM elements:
+ *    - `<tbw-grid-column>` → `effectiveConfig.columns`
+ *    - `<tbw-grid-header title="...">` → `effectiveConfig.shell.header.title`
+ *    - `<tbw-grid-header-content>` → `effectiveConfig.shell.header.content`
+ * 3. `columns` property → merged into `effectiveConfig.columns`
+ * 4. `fitMode` property → merged into `effectiveConfig.fitMode`
+ * 5. `editOn` property → merged into `effectiveConfig.editOn`
+ * 6. Column inference from first row (if no columns defined)
+ *
+ * **Derived State:**
+ * - `_columns` - processed columns from `effectiveConfig.columns` after plugin hooks
+ * - `_rows` - processed rows after plugin hooks (grouping, filtering, etc.)
+ *
+ * The `#mergeEffectiveConfig()` method is the single place where all inputs converge.
+ * All rendering and logic should read from `effectiveConfig` or derived state.
+ *
+ * @element tbw-grid
+ *
+ * @csspart container - The main grid container
+ * @csspart header - The header row container
+ * @csspart body - The body/rows container
+ *
+ * @fires cell-commit - Fired when a cell value is committed
+ * @fires row-commit - Fired when a bulk row edit session commits
+ * @fires changed-rows-reset - Fired after resetChangedRows() unless silent
+ * @fires mount-external-view - Fired to request mounting of an external view renderer
+ * @fires mount-external-editor - Fired to request mounting of an external editor renderer
+ * @fires sort-change - Fired when sort state changes for a column
+ * @fires column-resize - Fired after a column resize drag completes
+ * @fires activate-cell - Fired when a cell activation intent occurs
+ * @fires group-toggle - Fired when a group row is toggled
+ *
+ * @cssprop --tbw-color-bg - Background color
+ * @cssprop --tbw-color-fg - Foreground/text color
+ */
+export declare class DataGridElement<T = any> extends HTMLElement implements InternalGrid<T> {
+    #private;
+    static readonly tagName = "tbw-grid";
+    _rows: T[];
+    get _columns(): ColumnInternal<T>[];
+    set _columns(value: ColumnInternal<T>[]);
+    get visibleColumns(): ColumnInternal<T>[];
+    rowPool: HTMLElement[];
+    __rowRenderEpoch: number;
+    activeEditRows: number;
+    resizeController: ResizeController;
+    __didInitialAutoSize: boolean;
+    __lightDomColumnsCache?: ColumnInternal[];
+    __originalColumnNodes?: HTMLElement[];
+    headerRowEl: HTMLElement;
+    bodyEl: HTMLElement;
+    virtualization: VirtualState;
+    sortState: {
+        field: string;
+        direction: 1 | -1;
+    } | null;
+    __originalOrder: T[];
+    focusRow: number;
+    focusCol: number;
+    gridTemplate: string;
+    rowEditSnapshots: Map<number, T>;
+    _changedRowIndices: Set<number>;
+    get rows(): T[];
+    set rows(value: T[]);
+    /**
+     * Get the original unfiltered/unprocessed rows.
+     * Use this when you need access to all source data regardless of active filters.
+     */
+    get sourceRows(): T[];
+    get columns(): ColumnConfig<T>[];
+    set columns(value: ColumnConfig<T>[] | ColumnConfigMap<T> | undefined);
+    get gridConfig(): GridConfig<T>;
+    set gridConfig(value: GridConfig<T> | undefined);
+    get fitMode(): FitMode;
+    set fitMode(value: FitMode | undefined);
+    get editOn(): string | undefined;
+    set editOn(value: string | undefined);
+    get effectiveConfig(): GridConfig<T>;
+    constructor();
+    /**
+     * Get a plugin instance by its class.
+     * Used by plugins for inter-plugin communication.
+     */
+    getPlugin<P extends BaseGridPlugin>(PluginClass: new (...args: any[]) => P): P | undefined;
+    /**
+     * Get a plugin instance by its name.
+     * Used for loose coupling between plugins (avoids static imports).
+     */
+    getPluginByName(name: string): BaseGridPlugin | undefined;
+    /**
+     * Request a full re-render of the grid.
+     * Called by plugins when they need the grid to update.
+     * Note: This does NOT reset plugin state - just re-processes rows/columns and renders.
+     */
+    requestRender(): void;
+    /**
+     * Request a lightweight style update without rebuilding DOM.
+     * Called by plugins when they only need to update CSS classes/styles.
+     * This runs all plugin afterRender hooks without rebuilding row/column DOM.
+     */
+    requestAfterRender(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    emitCellCommit(detail: CellCommitDetail<T>): void;
+    emitRowCommit(detail: RowCommitDetail<T>): void;
+    emitSortChange(detail: SortChangeDetail): void;
+    emitColumnResize(detail: ColumnResizeDetail): void;
+    emitActivateCell(detail: ActivateCellDetail): void;
+    updateTemplate(): void;
+    findHeaderRow(): HTMLElement;
+    findRenderedRowElement(rowIndex: number): HTMLElement | null;
+    /**
+     * Dispatch a cell click event to the plugin system.
+     * Returns true if any plugin handled the event.
+     */
+    dispatchCellClick(event: MouseEvent, rowIndex: number, colIndex: number, cellEl: HTMLElement): boolean;
+    /**
+     * Dispatch a header click event to the plugin system.
+     * Returns true if any plugin handled the event.
+     */
+    dispatchHeaderClick(event: MouseEvent, colIndex: number, headerEl: HTMLElement): boolean;
+    /**
+     * Dispatch a keyboard event to the plugin system.
+     * Returns true if any plugin handled the event.
+     */
+    dispatchKeyDown(event: KeyboardEvent): boolean;
+    get changedRows(): T[];
+    get changedRowIndices(): number[];
+    resetChangedRows(silent?: boolean): Promise<void>;
+    beginBulkEdit(rowIndex: number): Promise<void>;
+    commitActiveRowEdit(): Promise<void>;
+    ready(): Promise<void>;
+    forceLayout(): Promise<void>;
+    /** Public method: returns a frozen snapshot of the merged effective configuration */
+    getConfig(): Promise<Readonly<GridConfig<T>>>;
+    /**
+     * Set the visibility of a column.
+     * @param field - The field name of the column
+     * @param visible - Whether the column should be visible
+     * @returns True if visibility was changed, false if column not found or locked
+     */
+    setColumnVisible(field: string, visible: boolean): boolean;
+    /**
+     * Toggle the visibility of a column.
+     * @param field - The field name of the column
+     * @returns True if visibility was toggled, false if column not found or locked
+     */
+    toggleColumnVisibility(field: string): boolean;
+    /**
+     * Check if a column is currently visible.
+     * @param field - The field name of the column
+     * @returns True if visible, false if hidden or not found
+     */
+    isColumnVisible(field: string): boolean;
+    /**
+     * Show all columns.
+     */
+    showAllColumns(): void;
+    /**
+     * Get list of all column fields (including hidden).
+     * Returns columns reflecting current display order (after reordering).
+     * Hidden columns are interleaved at their original relative positions.
+     * @returns Array of all field names with their visibility status
+     */
+    getAllColumns(): Array<{
+        field: string;
+        header: string;
+        visible: boolean;
+        lockVisible?: boolean;
+    }>;
+    /**
+     * Reorder columns according to the specified field order.
+     * This directly updates _columns in place without going through processColumns.
+     * @param order - Array of field names in the desired order
+     */
+    setColumnOrder(order: string[]): void;
+    /**
+     * Get the current column order as an array of field names.
+     * @returns Array of field names in display order
+     */
+    getColumnOrder(): string[];
+    /**
+     * Get the current column state, including order, width, visibility, sort, and plugin state.
+     * Returns a serializable object suitable for localStorage or database storage.
+     */
+    getColumnState(): GridColumnState;
+    /**
+     * Set the column state, restoring order, width, visibility, sort, and plugin state.
+     * Use this to restore previously saved column state.
+     */
+    set columnState(state: GridColumnState | undefined);
+    /**
+     * Get the current column state.
+     */
+    get columnState(): GridColumnState | undefined;
+    /**
+     * Request a state change event to be emitted.
+     * Called internally after resize, reorder, visibility, or sort changes.
+     * Plugins should call this after changing their state.
+     * The event is debounced to avoid excessive events during drag operations.
+     */
+    requestStateChange(): void;
+    /**
+     * Reset column state to initial configuration.
+     * Clears all user modifications (order, width, visibility, sort).
+     */
+    resetColumnState(): void;
+    /**
+     * Get the currently active tool panel ID, or null if none is open.
+     */
+    get activeToolPanel(): string | null;
+    /**
+     * Open a tool panel by ID.
+     * Closes any currently open panel first.
+     */
+    openToolPanel(panelId: string): void;
+    /**
+     * Close the currently open tool panel.
+     */
+    closeToolPanel(): void;
+    /**
+     * Toggle a tool panel open/closed.
+     */
+    toggleToolPanel(panelId: string): void;
+    /**
+     * Get registered tool panel definitions.
+     */
+    getToolPanels(): ToolPanelDefinition[];
+    /**
+     * Register a custom tool panel (without creating a plugin).
+     */
+    registerToolPanel(panel: ToolPanelDefinition): void;
+    /**
+     * Unregister a custom tool panel.
+     */
+    unregisterToolPanel(panelId: string): void;
+    /**
+     * Get registered header content definitions.
+     */
+    getHeaderContents(): HeaderContentDefinition[];
+    /**
+     * Register custom header content (without creating a plugin).
+     */
+    registerHeaderContent(content: HeaderContentDefinition): void;
+    /**
+     * Unregister custom header content.
+     */
+    unregisterHeaderContent(contentId: string): void;
+    /**
+     * Get all registered toolbar buttons.
+     */
+    getToolbarButtons(): ToolbarButtonInfo[];
+    /**
+     * Register a custom toolbar button programmatically.
+     */
+    registerToolbarButton(button: ToolbarButtonConfig): void;
+    /**
+     * Unregister a custom toolbar button.
+     */
+    unregisterToolbarButton(buttonId: string): void;
+    /**
+     * Enable/disable a toolbar button by ID.
+     */
+    setToolbarButtonDisabled(buttonId: string, disabled: boolean): void;
+    /**
+     * Re-parse light DOM shell elements and refresh shell header.
+     * Call this after dynamically modifying <tbw-grid-header> children.
+     */
+    refreshShellHeader(): void;
+    /**
+     * Core virtualization routine. Chooses between bypass (small datasets), grouped window rendering,
+     * or standard row window rendering.
+     */
+    refreshVirtualWindow(force?: boolean): void;
+}
+
+/**
+ * The compiled webcomponent interface for DataGrid
+ */
+export declare interface DataGridElementInterface extends PublicGrid, HTMLElement {
+}
+
+export declare interface DataGridEventMap<TRow = any> {
+    'cell-commit': CellCommitDetail<TRow>;
+    'row-commit': RowCommitDetail<TRow>;
+    'changed-rows-reset': ChangedRowsResetDetail<TRow>;
+    'mount-external-view': ExternalMountViewDetail<TRow>;
+    'mount-external-editor': ExternalMountEditorDetail<TRow>;
+    'sort-change': SortChangeDetail;
+    'column-resize': ColumnResizeDetail;
+    'activate-cell': ActivateCellDetail;
+    'column-state-change': GridColumnState;
+}
+
+export declare type DGEventName = (typeof DGEvents)[keyof typeof DGEvents];
+
+export declare const DGEvents: {
+    readonly CELL_COMMIT: "cell-commit";
+    readonly ROW_COMMIT: "row-commit";
+    readonly CHANGED_ROWS_RESET: "changed-rows-reset";
+    readonly MOUNT_EXTERNAL_VIEW: "mount-external-view";
+    readonly MOUNT_EXTERNAL_EDITOR: "mount-external-editor";
+    readonly SORT_CHANGE: "sort-change";
+    readonly COLUMN_RESIZE: "column-resize";
+    readonly ACTIVATE_CELL: "activate-cell";
+    readonly GROUP_TOGGLE: "group-toggle";
+    readonly COLUMN_STATE_CHANGE: "column-state-change";
+};
+
+/** Represents a single edit action that can be undone/redone */
+export declare interface EditAction {
+    /** Type of action - currently only 'cell-edit' is supported */
+    type: 'cell-edit';
+    /** The row index where the edit occurred */
+    rowIndex: number;
+    /** The field (column key) that was edited */
+    field: string;
+    /** The value before the edit */
+    oldValue: unknown;
+    /** The value after the edit */
+    newValue: unknown;
+    /** Unix timestamp when the edit occurred */
+    timestamp: number;
+}
+
+/**
+ * Internal editor execution context extending the generic cell context with commit helpers.
+ */
+declare interface EditorExecContext<T = any> extends CellContext<T> {
+    commit: (newValue: any) => void;
+    cancel: () => void;
+}
+
+/**
+ * Export Plugin Types
+ *
+ * Type definitions for the data export feature.
+ */
+/** Supported export formats */
+export declare type ExportFormat = 'csv' | 'excel' | 'json';
+
+/** Parameters for a specific export operation */
+export declare interface ExportParams {
+    /** Export format */
+    format: ExportFormat;
+    /** File name for the export (without extension) */
+    fileName?: string;
+    /** Specific column fields to export */
+    columns?: string[];
+    /** Specific row indices to export */
+    rowIndices?: number[];
+    /** Include column headers in export */
+    includeHeaders?: boolean;
+    /** Custom cell value processor */
+    processCell?: (value: any, field: string, row: any) => any;
+    /** Custom header processor */
+    processHeader?: (header: string, field: string) => string;
+}
+
+export declare interface ExternalMountEditorDetail<TRow = any> {
+    placeholder: HTMLElement;
+    spec: any;
+    context: {
+        row: TRow;
+        value: any;
+        field: string;
+        column: any;
+        commit: (v: any) => void;
+        cancel: () => void;
+    };
+}
+
+export declare interface ExternalMountViewDetail<TRow = any> {
+    placeholder: HTMLElement;
+    spec: any;
+    context: {
+        row: TRow;
+        value: any;
+        field: string;
+        column: any;
+    };
+}
+
+/** Configuration options for the filtering plugin */
+export declare interface FilterConfig {
+    /** Whether filtering is enabled (default: true) */
+    enabled?: boolean;
+    /** Debounce delay in ms for filter input (default: 300) */
+    debounceMs?: number;
+    /** Whether text filtering is case sensitive (default: false) */
+    caseSensitive?: boolean;
+    /** Whether to trim whitespace from filter input (default: true) */
+    trimInput?: boolean;
+    /** Use Web Worker for filtering large datasets >1000 rows (default: true) */
+    useWorker?: boolean;
+    /** Custom filter panel renderer (replaces default panel content) */
+    filterPanelRenderer?: FilterPanelRenderer;
+}
+
+/** Filter model representing a single filter condition */
+export declare interface FilterModel {
+    /** The field/column to filter on */
+    field: string;
+    /** The type of filter */
+    type: FilterType;
+    /** The filter operator */
+    operator: FilterOperator;
+    /** The filter value (type depends on operator) */
+    value: unknown;
+    /** Secondary value for 'between' operator */
+    valueTo?: unknown;
+}
+
+/** Filter operators for different filter types */
+export declare type FilterOperator = 'contains' | 'notContains' | 'equals' | 'notEquals' | 'startsWith' | 'endsWith' | 'blank' | 'notBlank' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual' | 'between' | 'in' | 'notIn';
+
+/** Parameters passed to custom filter panel renderer */
+declare interface FilterPanelParams {
+    /** The field being filtered */
+    field: string;
+    /** The column configuration */
+    column: ColumnConfig;
+    /** All unique values for this field */
+    uniqueValues: unknown[];
+    /** Currently excluded values (for set filter) */
+    excludedValues: Set<unknown>;
+    /** Current search text */
+    searchText: string;
+    /** Apply a set filter (exclude these values) */
+    applySetFilter: (excludedValues: unknown[]) => void;
+    /** Apply a text filter */
+    applyTextFilter: (operator: FilterOperator, value: string, valueTo?: string) => void;
+    /** Clear the filter for this field */
+    clearFilter: () => void;
+    /** Close the filter panel */
+    closePanel: () => void;
+}
+
+/** Custom filter panel renderer function. Return undefined to use default panel for this column. */
+declare type FilterPanelRenderer = (container: HTMLElement, params: FilterPanelParams) => void | undefined;
+
+/** Supported filter types */
+export declare type FilterType = 'text' | 'number' | 'date' | 'set' | 'boolean';
+
+export declare type FitMode = (typeof FitModeEnum)[keyof typeof FitModeEnum];
+
+export declare const FitModeEnum: {
+    readonly STRETCH: "stretch";
+    readonly FIXED: "fixed";
+};
+
+/** A flattened tree row with hierarchy metadata */
+declare interface FlattenedTreeRow {
+    /** Unique key identifying this row */
+    key: string;
+    /** Original row data */
+    data: any;
+    /** Depth level in the tree (0 = root) */
+    depth: number;
+    /** Whether this row has children */
+    hasChildren: boolean;
+    /** Whether this row is currently expanded */
+    isExpanded: boolean;
+    /** Key of the parent row, or null for root level */
+    parentKey: string | null;
+}
+
+export declare const getAggregator: (ref: AggregatorRef_2 | undefined) => AggregatorFn | undefined;
+
+export declare interface GetRowsParams {
+    startRow: number;
+    endRow: number;
+    sortModel?: Array<{
+        field: string;
+        direction: 'asc' | 'desc';
+    }>;
+    filterModel?: Record<string, any>;
+}
+
+export declare interface GetRowsResult {
+    rows: any[];
+    totalRowCount: number;
+    lastRow?: number;
+}
+
+/**
+ * CSS class names used in the grid's shadow DOM.
+ * Use these when adding/removing classes or querying elements.
+ */
+export declare const GridClasses: {
+    readonly ROOT: "tbw-grid-root";
+    readonly HEADER: "header";
+    readonly HEADER_ROW: "header-row";
+    readonly HEADER_CELL: "header-cell";
+    readonly ROWS_VIEWPORT: "rows-viewport";
+    readonly ROWS_SPACER: "rows-spacer";
+    readonly ROWS_CONTAINER: "rows";
+    readonly DATA_ROW: "data-row";
+    readonly GROUP_ROW: "group-row";
+    readonly DATA_CELL: "data-cell";
+    readonly SELECTED: "selected";
+    readonly FOCUSED: "focused";
+    readonly EDITING: "editing";
+    readonly EXPANDED: "expanded";
+    readonly COLLAPSED: "collapsed";
+    readonly DRAGGING: "dragging";
+    readonly RESIZING: "resizing";
+    readonly SORTABLE: "sortable";
+    readonly SORTED_ASC: "sorted-asc";
+    readonly SORTED_DESC: "sorted-desc";
+    readonly HIDDEN: "hidden";
+    readonly STICKY_LEFT: "sticky-left";
+    readonly STICKY_RIGHT: "sticky-right";
+    readonly PINNED_TOP: "pinned-top";
+    readonly PINNED_BOTTOM: "pinned-bottom";
+    readonly TREE_TOGGLE: "tree-toggle";
+    readonly TREE_INDENT: "tree-indent";
+    readonly GROUP_TOGGLE: "group-toggle";
+    readonly GROUP_LABEL: "group-label";
+    readonly GROUP_COUNT: "group-count";
+    readonly RANGE_SELECTION: "range-selection";
+    readonly SELECTION_OVERLAY: "selection-overlay";
+};
+
+export declare type GridClassName = (typeof GridClasses)[keyof typeof GridClasses];
+
+/**
+ * Complete grid column state for persistence.
+ * Contains state for all columns, including plugin-contributed properties.
+ */
+export declare interface GridColumnState {
+    columns: ColumnState[];
+}
+
+/**
+ * Grid configuration object - the **single source of truth** for grid behavior.
+ *
+ * Users can configure the grid via multiple input methods, all of which converge
+ * into an effective `GridConfig` internally:
+ *
+ * **Configuration Input Methods:**
+ * - `gridConfig` property - direct assignment of this object
+ * - `columns` property - shorthand for `gridConfig.columns`
+ * - `fitMode` property - shorthand for `gridConfig.fitMode`
+ * - `editOn` property - shorthand for `gridConfig.editOn`
+ * - Light DOM `<tbw-grid-column>` - declarative columns (merged into `columns`)
+ * - Light DOM `<tbw-grid-header>` - declarative shell header (merged into `shell.header`)
+ *
+ * **Precedence (when same property set multiple ways):**
+ * Individual props (`fitMode`, `editOn`) > `columns` prop > Light DOM > `gridConfig`
+ *
+ * @example
+ * ```ts
+ * // Via gridConfig (recommended for complex setups)
+ * grid.gridConfig = {
+ *   columns: [{ field: 'name' }, { field: 'age' }],
+ *   fitMode: 'stretch',
+ *   plugins: [new SelectionPlugin()],
+ *   shell: { header: { title: 'My Grid' } }
+ * };
+ *
+ * // Via individual props (convenience for simple cases)
+ * grid.columns = [{ field: 'name' }, { field: 'age' }];
+ * grid.fitMode = 'stretch';
+ * ```
+ */
+export declare interface GridConfig<TRow = any> {
+    /** Column definitions. Can also be set via `columns` prop or `<tbw-grid-column>` light DOM. */
+    columns?: ColumnConfigMap<TRow>;
+    /** Sizing mode for columns. Can also be set via `fitMode` prop. */
+    fitMode?: FitMode;
+    /** Edit activation mode ('click' | 'dblclick'). Can also be set via `editOn` prop. */
+    editOn?: string;
+    /**
+     * Array of plugin instances.
+     * Each plugin is instantiated with its configuration and attached to this grid.
+     *
+     * @example
+     * ```ts
+     * plugins: [
+     *   new SelectionPlugin({ mode: 'range' }),
+     *   new MultiSortPlugin(),
+     *   new FilteringPlugin({ debounceMs: 150 }),
+     * ]
+     * ```
+     */
+    plugins?: any[];
+    /**
+     * Saved column state to restore on initialization.
+     * Includes order, width, visibility, sort, and plugin-contributed state.
+     */
+    columnState?: GridColumnState;
+    /**
+     * Shell configuration for header bar and tool panels.
+     * When configured, adds an optional wrapper with title, toolbar, and collapsible side panels.
+     */
+    shell?: ShellConfig;
+}
+
+export declare type GridCSSVar = (typeof GridCSSVars)[keyof typeof GridCSSVars];
+
+/**
+ * CSS custom property names for theming.
+ * Use these when programmatically setting styles.
+ */
+export declare const GridCSSVars: {
+    readonly COLOR_BG: "--tbw-color-bg";
+    readonly COLOR_FG: "--tbw-color-fg";
+    readonly COLOR_FG_MUTED: "--tbw-color-fg-muted";
+    readonly COLOR_BORDER: "--tbw-color-border";
+    readonly COLOR_ACCENT: "--tbw-color-accent";
+    readonly COLOR_HEADER_BG: "--tbw-color-header-bg";
+    readonly COLOR_HEADER_FG: "--tbw-color-header-fg";
+    readonly COLOR_SELECTION: "--tbw-color-selection";
+    readonly COLOR_ROW_HOVER: "--tbw-color-row-hover";
+    readonly COLOR_ROW_ALT: "--tbw-color-row-alt";
+    readonly ROW_HEIGHT: "--tbw-row-height";
+    readonly HEADER_HEIGHT: "--tbw-header-height";
+    readonly CELL_PADDING: "--tbw-cell-padding";
+    readonly FONT_FAMILY: "--tbw-font-family";
+    readonly FONT_SIZE: "--tbw-font-size";
+    readonly BORDER_RADIUS: "--tbw-border-radius";
+    readonly FOCUS_OUTLINE: "--tbw-focus-outline";
+};
+
+export declare type GridDataAttr = (typeof GridDataAttrs)[keyof typeof GridDataAttrs];
+
+/**
+ * Data attribute names used on grid elements.
+ * Use these when getting/setting data attributes.
+ */
+export declare const GridDataAttrs: {
+    readonly ROW_INDEX: "data-row-index";
+    readonly COL_INDEX: "data-col-index";
+    readonly FIELD: "data-field";
+    readonly GROUP_KEY: "data-group-key";
+    readonly TREE_LEVEL: "data-tree-level";
+    readonly STICKY: "data-sticky";
+};
+
+export declare interface GridElement {
+    shadowRoot: ShadowRoot | null;
+    rows: any[];
+    columns: ColumnConfig[];
+    gridConfig: any;
+    requestRender(): void;
+    requestAfterRender(): void;
+    forceLayout(): Promise<void>;
+    getPlugin<T extends BaseGridPlugin>(PluginClass: new (...args: any[]) => T): T | undefined;
+    getPluginByName(name: string): BaseGridPlugin | undefined;
+    dispatchEvent(event: Event): boolean;
+}
+
+/**
+ * Common CSS selectors for querying grid elements.
+ * Built from the class constants for consistency.
+ */
+export declare const GridSelectors: {
+    readonly ROOT: ".tbw-grid-root";
+    readonly HEADER: ".header";
+    readonly HEADER_ROW: ".header-row";
+    readonly HEADER_CELL: ".header-cell";
+    readonly ROWS_VIEWPORT: ".rows-viewport";
+    readonly ROWS_CONTAINER: ".rows";
+    readonly DATA_ROW: ".data-row";
+    readonly DATA_CELL: ".data-cell";
+    readonly GROUP_ROW: ".group-row";
+    readonly ROW_BY_INDEX: (index: number) => string;
+    readonly CELL_BY_FIELD: (field: string) => string;
+    readonly CELL_AT: (row: number, col: number) => string;
+    readonly SELECTED_ROWS: ".data-row.selected";
+    readonly EDITING_CELL: ".data-cell.editing";
+};
+
+/** Configuration options for the row grouping plugin */
+export declare interface GroupingRowsConfig {
+    /** Whether the plugin is enabled (default: true) */
+    enabled?: boolean;
+    /**
+     * Callback to determine group path for a row.
+     * Return an array of group keys, a single key, null/false to skip grouping.
+     */
+    groupOn?: (row: any) => any[] | any | null | false;
+    /** Whether groups are expanded by default (default: false) */
+    defaultExpanded?: boolean;
+    /** Custom group row renderer */
+    groupRowRenderer?: (params: GroupRowRenderParams) => HTMLElement | string | void;
+    /** Show row count in group headers (default: true) */
+    showRowCount?: boolean;
+    /** Indent width per depth level in pixels (default: 20) */
+    indentWidth?: number;
+    /** Aggregators for group row cells by field name */
+    aggregators?: AggregatorMap;
+    /** Custom format function for group label */
+    formatLabel?: (value: any, depth: number, key: string) => string;
+    /** Whether to render group row as full-width spanning cell (default: true) */
+    fullWidth?: boolean;
+}
+
+/** Parameters passed to custom group row renderer */
+declare interface GroupRowRenderParams {
+    /** The group key */
+    key: string;
+    /** The group value (last segment of path) */
+    value: any;
+    /** Depth level (0-based) */
+    depth: number;
+    /** All data rows in this group (including nested) */
+    rows: any[];
+    /** Whether the group is expanded */
+    expanded: boolean;
+    /** Toggle expand/collapse */
+    toggleExpand: () => void;
+}
+
+/**
+ * Header click event
+ */
+export declare interface HeaderClickEvent {
+    colIndex: number;
+    field: string;
+    column: ColumnConfig;
+    headerEl: HTMLElement;
+    originalEvent: MouseEvent;
+}
+
+/**
+ * Header content definition for plugins contributing to shell header center section.
+ */
+export declare interface HeaderContentDefinition {
+    /** Unique content ID */
+    id: string;
+    /** Content factory - called once when shell header renders */
+    render: (container: HTMLElement) => void | (() => void);
+    /** Called when content is removed (for cleanup) */
+    onDestroy?: () => void;
+    /** Order priority (lower = first, default: 100) */
+    order?: number;
+}
+
+/**
+ * Header renderer function type for plugins.
+ */
+export declare type HeaderRenderer = (ctx: PluginHeaderRenderContext) => string | HTMLElement;
+
+/** Result of automatic column inference from sample rows. */
+export declare interface InferredColumnResult<TRow = any> {
+    columns: ColumnConfigMap<TRow>;
+    typeMap: Record<string, PrimitiveColumnType>;
+}
+
+/**
+ * Internal-only augmented interface for DataGrid component
+ */
+declare interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
+    shadowRoot: ShadowRoot | null;
+    _rows: T[];
+    _columns: ColumnInternal<T>[];
+    /** Visible columns only (excludes hidden). Use for rendering. */
+    visibleColumns: ColumnInternal<T>[];
+    headerRowEl: HTMLElement;
+    bodyEl: HTMLElement;
+    rowPool: HTMLElement[];
+    resizeController: ResizeController;
+    sortState: {
+        field: string;
+        direction: 1 | -1;
+    } | null;
+    __originalOrder: T[];
+    __rowRenderEpoch: number;
+    __didInitialAutoSize?: boolean;
+    __lightDomColumnsCache?: ColumnInternal[];
+    __originalColumnNodes?: HTMLElement[];
+    gridTemplate: string;
+    virtualization: VirtualState;
+    focusRow: number;
+    focusCol: number;
+    activeEditRows: number;
+    rowEditSnapshots: Map<number, any>;
+    _changedRowIndices: Set<number>;
+    changedRows?: T[];
+    changedRowIndices?: number[];
+    effectiveConfig?: GridConfig<T>;
+    findHeaderRow?: () => HTMLElement;
+    refreshVirtualWindow: (full: boolean) => void;
+    updateTemplate?: () => void;
+    findRenderedRowElement?: (rowIndex: number) => HTMLElement | null;
+    beginBulkEdit?: (rowIndex: number) => void;
+    commitActiveRowEdit?: () => void;
+    /** Dispatch cell click to plugin system, returns true if handled */
+    dispatchCellClick?: (event: MouseEvent, rowIndex: number, colIndex: number, cellEl: HTMLElement) => boolean;
+    /** Dispatch header click to plugin system, returns true if handled */
+    dispatchHeaderClick?: (event: MouseEvent, colIndex: number, headerEl: HTMLElement) => boolean;
+    /** Dispatch keydown to plugin system, returns true if handled */
+    dispatchKeyDown?: (event: KeyboardEvent) => boolean;
+    /** Request emission of column-state-change event (debounced) */
+    requestStateChange?: () => void;
+}
+
+/**
+ * Keyboard modifier flags
+ */
+export declare interface KeyboardModifiers {
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+}
+
+export declare const listAggregators: () => string[];
+
+/** Configuration options for the multi-sort plugin */
+export declare interface MultiSortConfig {
+    /** Whether multi-sort is enabled (default: true) */
+    enabled?: boolean;
+    /** Maximum number of columns to sort by (default: 3) */
+    maxSortColumns?: number;
+    /** Whether to show sort order badges (1, 2, 3) on headers (default: true) */
+    showSortIndex?: boolean;
+}
+
+/** Context provided to panel renderers */
+export declare interface PinnedRowsContext {
+    /** Total number of rows in the grid */
+    totalRows: number;
+    /** Number of rows after filtering */
+    filteredRows: number;
+    /** Number of selected rows */
+    selectedRows: number;
+    /** Current column configuration */
+    columns: ColumnConfig[];
+    /** Current row data */
+    rows: unknown[];
+    /** Reference to the grid element */
+    grid: HTMLElement;
+}
+
+/** Custom panel definition for the status bar */
+export declare interface PinnedRowsPanel {
+    /** Unique identifier for the panel */
+    id: string;
+    /** Position within the status bar */
+    position: 'left' | 'center' | 'right';
+    /** Render function for the panel content */
+    render: (context: PinnedRowsContext) => HTMLElement | string;
+}
+
+export declare interface PivotConfig {
+    enabled?: boolean;
+    rowGroupFields?: string[];
+    columnGroupFields?: string[];
+    valueFields?: PivotValueField[];
+    showTotals?: boolean;
+    showGrandTotal?: boolean;
+}
+
+export declare interface PivotResult {
+    rows: PivotRow[];
+    columnKeys: string[];
+    totals: Record<string, number>;
+    grandTotal: number;
+}
+
+declare interface PivotRow {
+    rowKey: string;
+    rowLabel: string;
+    depth: number;
+    values: Record<string, number | null>;
+    total?: number;
+    isGroup: boolean;
+    children?: PivotRow[];
+}
+
+export declare interface PivotValueField {
+    field: string;
+    aggFunc: 'sum' | 'avg' | 'count' | 'min' | 'max' | 'first' | 'last';
+    header?: string;
+}
+
+/**
+ * Cell render context for plugin cell renderers.
+ * Provides full context including position and editing state.
+ *
+ * Note: This differs from the core `CellRenderContext` in types.ts which is
+ * simpler and used for column view renderers. This version provides additional
+ * context needed by plugins that register custom cell renderers.
+ */
+export declare interface PluginCellRenderContext {
+    /** The cell value */
+    value: any;
+    /** The field/column key */
+    field: string;
+    /** The row data object */
+    row: any;
+    /** Row index in the data array */
+    rowIndex: number;
+    /** Column index */
+    colIndex: number;
+    /** Column configuration */
+    column: ColumnConfig;
+    /** Whether the cell is currently in edit mode */
+    isEditing: boolean;
+}
+
+export declare type PluginEventName = (typeof PluginEvents)[keyof typeof PluginEvents];
+
+export declare const PluginEvents: {
+    readonly SELECTION_CHANGE: "selection-change";
+    readonly TREE_EXPAND: "tree-expand";
+    readonly FILTER_CHANGE: "filter-change";
+    readonly SORT_MODEL_CHANGE: "sort-model-change";
+    readonly EXPORT_START: "export-start";
+    readonly EXPORT_COMPLETE: "export-complete";
+    readonly CLIPBOARD_COPY: "clipboard-copy";
+    readonly CLIPBOARD_PASTE: "clipboard-paste";
+    readonly CONTEXT_MENU_OPEN: "context-menu-open";
+    readonly CONTEXT_MENU_CLOSE: "context-menu-close";
+    readonly HISTORY_CHANGE: "history-change";
+    readonly SERVER_LOADING: "server-loading";
+    readonly SERVER_ERROR: "server-error";
+    readonly COLUMN_VISIBILITY_CHANGE: "column-visibility-change";
+    readonly COLUMN_REORDER: "column-reorder";
+    readonly DETAIL_EXPAND: "detail-expand";
+    readonly GROUP_EXPAND: "group-expand";
+};
+
+/**
+ * Header render context for plugin header renderers.
+ */
+export declare interface PluginHeaderRenderContext {
+    /** Column configuration */
+    column: ColumnConfig;
+    /** Column index */
+    colIndex: number;
+}
+
+/**
+ * Manages plugins for a single grid instance.
+ */
+export declare class PluginManager {
+    private grid;
+    /** Plugin instances in order of attachment */
+    private plugins;
+    /** Map from plugin class to instance for fast lookup */
+    private pluginMap;
+    /** Cell renderers registered by plugins */
+    private cellRenderers;
+    /** Header renderers registered by plugins */
+    private headerRenderers;
+    /** Cell editors registered by plugins */
+    private cellEditors;
+    constructor(grid: any);
+    /**
+     * Attach all plugins from the config.
+     */
+    attachAll(plugins: BaseGridPlugin[]): void;
+    /**
+     * Attach a plugin to this grid.
+     */
+    attach(plugin: BaseGridPlugin): void;
+    /**
+     * Detach all plugins and clean up.
+     */
+    detachAll(): void;
+    /**
+     * Get a plugin instance by its class.
+     */
+    getPlugin<T extends BaseGridPlugin>(PluginClass: new (...args: any[]) => T): T | undefined;
+    /**
+     * Get a plugin instance by its name.
+     */
+    getPluginByName(name: string): BaseGridPlugin | undefined;
+    /**
+     * Check if a plugin is attached.
+     */
+    hasPlugin<T extends BaseGridPlugin>(PluginClass: new (...args: any[]) => T): boolean;
+    /**
+     * Get all attached plugins.
+     */
+    getAll(): readonly BaseGridPlugin[];
+    /**
+     * Get a cell renderer by type name.
+     */
+    getCellRenderer(type: string): CellRenderer | undefined;
+    /**
+     * Get a header renderer by type name.
+     */
+    getHeaderRenderer(type: string): HeaderRenderer | undefined;
+    /**
+     * Get a cell editor by type name.
+     */
+    getCellEditor(type: string): CellEditor | undefined;
+    /**
+     * Get all CSS styles from all plugins.
+     */
+    getAllStyles(): string;
+    /**
+     * Execute processRows hook on all plugins.
+     */
+    processRows(rows: readonly any[]): any[];
+    /**
+     * Execute processColumns hook on all plugins.
+     */
+    processColumns(columns: readonly ColumnConfig[]): ColumnConfig[];
+    /**
+     * Execute beforeRender hook on all plugins.
+     */
+    beforeRender(): void;
+    /**
+     * Execute afterRender hook on all plugins.
+     */
+    afterRender(): void;
+    /**
+     * Execute renderRow hook on all plugins.
+     * Returns true if any plugin handled the row.
+     */
+    renderRow(row: any, rowEl: HTMLElement, rowIndex: number): boolean;
+    /**
+     * Execute onKeyDown hook on all plugins.
+     * Returns true if any plugin handled the event.
+     */
+    onKeyDown(event: KeyboardEvent): boolean;
+    /**
+     * Execute onCellClick hook on all plugins.
+     * Returns true if any plugin handled the event.
+     */
+    onCellClick(event: CellClickEvent): boolean;
+    /**
+     * Execute onRowClick hook on all plugins.
+     * Returns true if any plugin handled the event.
+     */
+    onRowClick(event: RowClickEvent): boolean;
+    /**
+     * Execute onHeaderClick hook on all plugins.
+     * Returns true if any plugin handled the event.
+     */
+    onHeaderClick(event: HeaderClickEvent): boolean;
+    /**
+     * Execute onScroll hook on all plugins.
+     */
+    onScroll(event: ScrollEvent): void;
+    /**
+     * Execute onCellMouseDown hook on all plugins.
+     * Returns true if any plugin handled the event.
+     */
+    onCellMouseDown(event: CellMouseEvent): boolean;
+    /**
+     * Execute onCellMouseMove hook on all plugins.
+     * Returns true if any plugin handled the event.
+     */
+    onCellMouseMove(event: CellMouseEvent): boolean;
+    /**
+     * Execute onCellMouseUp hook on all plugins.
+     * Returns true if any plugin handled the event.
+     */
+    onCellMouseUp(event: CellMouseEvent): boolean;
+    /**
+     * Collect context menu items from all plugins.
+     */
+    getContextMenuItems(params: ContextMenuParams): ContextMenuItem[];
+    /**
+     * Collect tool panels from all plugins.
+     * Returns panels sorted by order (ascending).
+     */
+    getToolPanels(): {
+        plugin: BaseGridPlugin;
+        panel: NonNullable<ReturnType<NonNullable<BaseGridPlugin['getToolPanel']>>>;
+    }[];
+    /**
+     * Collect header contents from all plugins.
+     * Returns contents sorted by order (ascending).
+     */
+    getHeaderContents(): {
+        plugin: BaseGridPlugin;
+        content: NonNullable<ReturnType<NonNullable<BaseGridPlugin['getHeaderContent']>>>;
+    }[];
+}
+
+export declare type PrimitiveColumnType = 'number' | 'string' | 'date' | 'boolean' | 'select' | 'typeahead';
+
+/**
+ * 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
+ */
+export declare interface PublicGrid<T = any> {
+    /**
+     * Full config object. Setter merges with other inputs per precedence rules.
+     * Getter returns the effective (resolved) config.
+     */
+    gridConfig?: GridConfig<T>;
+    /**
+     * Column definitions.
+     * Getter returns effective columns (after merging config, light DOM, inference).
+     */
+    columns?: ColumnConfig<T>[];
+    /** Current row data (after plugin processing like grouping, filtering). */
+    rows?: T[];
+    /** Resolves once the component has finished initial work (layout, inference). */
+    ready?: () => Promise<void>;
+    /** Force a layout / measurement pass (e.g. after container resize). */
+    forceLayout?: () => Promise<void>;
+    /** Return effective resolved config (after inference & precedence). */
+    getConfig?: () => Promise<Readonly<GridConfig<T>>>;
+    /** Toggle expansion state of a group row by its generated key. */
+    toggleGroup?: (key: string) => Promise<void>;
+}
+
+export declare const registerAggregator: (name: string, fn: AggregatorFn) => void;
+
+/** Controller managing drag-based column resize lifecycle. */
+declare interface ResizeController {
+    start: (e: MouseEvent, colIndex: number, cell: HTMLElement) => void;
+    dispose: () => void;
+    /** True while a resize drag is in progress (used to suppress header click/sort). */
+    isResizing: boolean;
+}
+
+/**
+ * Row click event
+ */
+export declare interface RowClickEvent {
+    rowIndex: number;
+    row: any;
+    rowEl: HTMLElement;
+    originalEvent: MouseEvent;
+}
+
+/** Detail payload for a committed row edit (may or may not include changes). */
+export declare interface RowCommitDetail<TRow = any> {
+    /** Row index that lost edit focus. */
+    rowIndex: number;
+    /** Row object reference. */
+    row: TRow;
+    /** Whether any cell changes were actually committed in this row during the session. */
+    changed: boolean;
+    /** Current changed row collection. */
+    changedRows: TRow[];
+    /** Indices of changed rows. */
+    changedRowIndices: number[];
+}
+
+/**
+ * Group row rendering customization options.
+ * Used within grouping-rows plugin config for presentation of group rows.
+ */
+export declare interface RowGroupRenderConfig {
+    /** If true, group rows span all columns (single full-width cell). Default false. */
+    fullWidth?: boolean;
+    /** Optional label formatter override. Receives raw group value + depth. */
+    formatLabel?: (value: any, depth: number, key: string) => string;
+    /** Optional aggregate overrides per field for group summary cells (only when not fullWidth). */
+    aggregators?: Record<string, AggregatorRef>;
+    /** Additional CSS class applied to each group row root element. */
+    class?: string;
+}
+
+export declare const runAggregator: (ref: AggregatorRef_2 | undefined, rows: any[], field: string, column?: any) => any;
+
+/**
+ * Scroll event
+ */
+export declare interface ScrollEvent {
+    scrollTop: number;
+    scrollLeft: number;
+    scrollHeight: number;
+    scrollWidth: number;
+    clientHeight: number;
+    clientWidth: number;
+    originalEvent?: Event;
+}
+
+/**
+ * Unified event detail emitted when selection changes (all modes).
+ * Provides a consistent structure for consumers to handle selection state.
+ */
+export declare interface SelectionChangeDetail {
+    /** The selection mode that triggered this event */
+    mode: SelectionMode_2;
+    /** Selected cell ranges. For cell mode, contains a single-cell range. For row mode, contains full-row ranges. */
+    ranges: CellRange[];
+}
+
+/** Configuration options for the selection plugin */
+export declare interface SelectionConfig {
+    /** Selection mode (default: 'cell') */
+    mode: SelectionMode_2;
+}
+
+/**
+ * Selection Plugin Types
+ *
+ * Type definitions for the selection feature.
+ */
+/**
+ * Selection mode for the grid:
+ * - 'cell': Single cell selection (default). No border, just focus highlight.
+ * - 'row': Row selection. Clicking a cell selects the entire row. Uses focus outline color.
+ * - 'range': Range selection. Shift+click or drag to select rectangular cell ranges. Uses success border color.
+ */
+declare type SelectionMode_2 = 'cell' | 'row' | 'range';
+export { SelectionMode_2 as SelectionMode }
+
+/**
+ * Selection Plugin for tbw-grid
+ *
+ * @example
+ * ```ts
+ * new SelectionPlugin({ mode: 'range' })
+ * ```
+ */
+export declare class SelectionPlugin extends BaseGridPlugin<SelectionConfig> {
+    #private;
+    readonly name = "selection";
+    readonly version = "1.0.0";
+    protected get defaultConfig(): Partial<SelectionConfig>;
+    /** Row selection state (row mode) */
+    private selected;
+    private lastSelected;
+    private anchor;
+    /** Range selection state (range mode) */
+    private ranges;
+    private activeRange;
+    private cellAnchor;
+    private isDragging;
+    /** Cell selection state (cell mode) */
+    private selectedCell;
+    detach(): void;
+    onCellClick(event: CellClickEvent): boolean;
+    onKeyDown(event: KeyboardEvent): boolean;
+    onCellMouseDown(event: CellMouseEvent): boolean | void;
+    onCellMouseMove(event: CellMouseEvent): boolean | void;
+    onCellMouseUp(_event: CellMouseEvent): boolean | void;
+    afterRender(): void;
+    /**
+     * Get the selected cell (cell mode only).
+     */
+    getSelectedCell(): {
+        row: number;
+        col: number;
+    } | null;
+    /**
+     * Get all selected row indices (row mode).
+     */
+    getSelectedRows(): number[];
+    /**
+     * Get all selected cell ranges in public format.
+     */
+    getRanges(): CellRange[];
+    /**
+     * Get all selected cells across all ranges.
+     */
+    getSelectedCells(): Array<{
+        row: number;
+        col: number;
+    }>;
+    /**
+     * Check if a specific cell is in range selection.
+     */
+    isCellSelected(row: number, col: number): boolean;
+    /**
+     * Clear all selection.
+     */
+    clearSelection(): void;
+    /**
+     * Set selected ranges programmatically.
+     */
+    setRanges(ranges: CellRange[]): void;
+    readonly styles = "\n    /* Prevent text selection during range drag */\n    :host .selecting .data-grid-row > .cell {\n      user-select: none;\n    }\n\n    /* Row selection - use accent color for row focus */\n    :host .data-grid-row.row-focus {\n      background-color: var(--tbw-focus-background, rgba(from var(--tbw-color-accent) r g b / 12%));\n    }\n\n    /* Disable cell-focus outline in row mode - row is the focus unit */\n    :host([data-selection-mode=\"row\"]) .cell-focus {\n      outline: none;\n    }\n\n    /* Selection cell styles - for range mode */\n    :host .data-grid-row > .cell.selected {\n      background-color: var(--tbw-range-selection-bg);\n    }\n    :host .data-grid-row > .cell.selected.top {\n      border-top: 2px solid var(--tbw-range-border-color);\n    }\n    :host .data-grid-row > .cell.selected.bottom {\n      border-bottom: 2px solid var(--tbw-range-border-color);\n    }\n    :host .data-grid-row > .cell.selected.first {\n      border-left: 2px solid var(--tbw-range-border-color);\n    }\n    :host .data-grid-row > .cell.selected.last {\n      border-right: 2px solid var(--tbw-range-border-color);\n    }\n  ";
+}
+
+export declare interface ServerSideDataSource {
+    getRows(params: GetRowsParams): Promise<GetRowsResult>;
+}
+
+/**
+ * Shell configuration for the grid's optional header bar and tool panels.
+ */
+export declare interface ShellConfig {
+    /** Shell header bar configuration */
+    header?: ShellHeaderConfig;
+    /** Tool panel configuration */
+    toolPanel?: ToolPanelConfig;
+}
+
+/**
+ * Shell header bar configuration
+ */
+export declare interface ShellHeaderConfig {
+    /** Grid title displayed on the left (optional) */
+    title?: string;
+    /** Custom toolbar buttons (rendered before tool panel toggles) */
+    toolbarButtons?: ToolbarButtonConfig[];
+}
+
+/** Detail for a sort change (direction 0 indicates cleared sort). */
+export declare interface SortChangeDetail {
+    /** Sorted field key. */
+    field: string;
+    /** Direction: 1 ascending, -1 descending, 0 cleared. */
+    direction: 1 | -1 | 0;
+}
+
+/**
+ * Multi-Sort Plugin Types
+ *
+ * Type definitions for the multi-column sorting feature.
+ */
+/** Represents a single column sort configuration */
+export declare interface SortModel {
+    /** The field key to sort by */
+    field: string;
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+}
+
+/**
+ * Toolbar button defined via config (programmatic approach).
+ * Supports three modes:
+ * - Simple: provide `icon` + `action` for grid to create button
+ * - Element: provide `element` for user-created DOM
+ * - Render: provide `render` function for complex widgets
+ */
+export declare interface ToolbarButtonConfig {
+    /** Unique button ID */
+    id: string;
+    /** Tooltip / aria-label (required for accessibility) */
+    label: string;
+    /** Order priority (lower = first, default: 100) */
+    order?: number;
+    /** Whether button is disabled (only applies to grid-rendered buttons) */
+    disabled?: boolean;
+    /** Button content: SVG string, emoji, or text. Grid creates <button> with this. */
+    icon?: string;
+    /** Click handler (required when using icon) */
+    action?: () => void;
+    /**
+     * User-provided element. Grid wraps it but doesn't modify it.
+     * User is responsible for event handlers.
+     */
+    element?: HTMLElement;
+    /**
+     * Render function called once. Receives container, user appends their DOM.
+     * User is responsible for event handlers.
+     * Return a cleanup function (optional).
+     */
+    render?: (container: HTMLElement) => void | (() => void);
+}
+
+/**
+ * Toolbar button info returned by getToolbarButtons().
+ */
+declare interface ToolbarButtonInfo {
+    id: string;
+    label: string;
+    disabled: boolean;
+    /** Source of this button: 'config' | 'light-dom' | 'panel-toggle' */
+    source: 'config' | 'light-dom' | 'panel-toggle';
+    /** For panel toggles, the associated panel ID */
+    panelId?: string;
+}
+
+/**
+ * Tool panel configuration
+ */
+export declare interface ToolPanelConfig {
+    /** Panel position: 'left' | 'right' (default: 'right') */
+    position?: 'left' | 'right';
+    /** Default panel width in pixels (default: 280) */
+    width?: number;
+    /** Panel ID to open by default on load */
+    defaultOpen?: string;
+    /** Whether to persist open/closed state (requires Column State Events) */
+    persistState?: boolean;
+}
+
+/**
+ * Tool panel definition registered by plugins or consumers.
+ */
+export declare interface ToolPanelDefinition {
+    /** Unique panel ID */
+    id: string;
+    /** Panel title shown in header */
+    title: string;
+    /** Icon for toolbar button (SVG string or emoji) */
+    icon: string;
+    /** Toolbar button tooltip */
+    tooltip?: string;
+    /** Panel content factory - called when panel opens */
+    render: (container: HTMLElement) => void | (() => void);
+    /** Called when panel closes (for cleanup) */
+    onClose?: () => void;
+    /** Panel order priority (lower = first, default: 100) */
+    order?: number;
+}
+
+/**
+ * Tree Data Plugin Types
+ *
+ * Type definitions for hierarchical tree data with expand/collapse functionality.
+ */
+/** Configuration options for the tree plugin */
+export declare interface TreeConfig {
+    /** Whether tree functionality is enabled (default: true) */
+    enabled?: boolean;
+    /** Field name containing child rows (default: 'children') */
+    childrenField?: string;
+    /** Auto-detect tree structure from data (default: true) */
+    autoDetect?: boolean;
+    /** Whether nodes are expanded by default (default: false) */
+    defaultExpanded?: boolean;
+    /** Indentation width per level in pixels (default: 20) */
+    indentWidth?: number;
+    /** Show expand/collapse icons (default: true) */
+    showExpandIcons?: boolean;
+}
+
+/** Event detail emitted when a tree node is expanded or collapsed */
+export declare interface TreeExpandDetail {
+    /** The row key that was toggled */
+    key: string;
+    /** The original row data */
+    row: any;
+    /** Whether the row is now expanded */
+    expanded: boolean;
+    /** Depth level of the row */
+    depth: number;
+}
+
+/**
+ * Tree Data Plugin for tbw-grid
+ *
+ * Provides hierarchical tree data display with expand/collapse functionality.
+ *
+ * @example
+ * ```ts
+ * new TreePlugin({ defaultExpanded: true, indentWidth: 24 })
+ * ```
+ */
+export declare class TreePlugin extends BaseGridPlugin<TreeConfig> {
+    readonly name = "tree";
+    readonly version = "1.0.0";
+    protected get defaultConfig(): Partial<TreeConfig>;
+    /** Set of expanded row keys */
+    private expandedKeys;
+    /** Whether initial expansion (based on defaultExpanded config) has been applied */
+    private initialExpansionDone;
+    /** Flattened tree rows for rendering */
+    private flattenedRows;
+    /** Map from key to flattened row for quick lookup */
+    private rowKeyMap;
+    detach(): void;
+    /**
+     * Detects if tree functionality should be enabled based on data structure.
+     * Called by the grid during plugin initialization.
+     */
+    detect(rows: readonly unknown[]): boolean;
+    processRows(rows: readonly unknown[]): any[];
+    processColumns(columns: readonly ColumnConfig[]): ColumnConfig[];
+    onCellClick(event: CellClickEvent): boolean;
+    /**
+     * Expand a specific node by key.
+     */
+    expand(key: string): void;
+    /**
+     * Collapse a specific node by key.
+     */
+    collapse(key: string): void;
+    /**
+     * Toggle the expansion state of a node.
+     */
+    toggle(key: string): void;
+    /**
+     * Expand all nodes in the tree.
+     */
+    expandAll(): void;
+    /**
+     * Collapse all nodes in the tree.
+     */
+    collapseAll(): void;
+    /**
+     * Check if a node is currently expanded.
+     */
+    isExpanded(key: string): boolean;
+    /**
+     * Get all currently expanded keys.
+     */
+    getExpandedKeys(): string[];
+    /**
+     * Get the flattened tree rows with metadata.
+     */
+    getFlattenedRows(): FlattenedTreeRow[];
+    /**
+     * Get a row's original data by its key.
+     */
+    getRowByKey(key: string): any | undefined;
+    /**
+     * Expand all ancestors of a node to make it visible.
+     */
+    expandToKey(key: string): void;
+    readonly styles = "\n    .tree-toggle {\n      cursor: pointer;\n      user-select: none;\n      transition: transform 0.2s;\n    }\n    .tree-toggle:hover {\n      color: var(--tbw-tree-accent, var(--tbw-color-accent));\n    }\n  ";
+}
+
+export declare const unregisterAggregator: (name: string) => void;
+
+/** Virtual window bookkeeping; modified in-place as scroll position changes. */
+declare interface VirtualState {
+    enabled: boolean;
+    rowHeight: number;
+    /** Threshold for bypassing virtualization (renders all rows if totalRows <= bypassThreshold) */
+    bypassThreshold: number;
+    start: number;
+    end: number;
+    /** Faux scrollbar element that provides scroll events (AG Grid pattern) */
+    container: HTMLElement | null;
+    /** Rows viewport element for measuring visible area height */
+    viewportEl: HTMLElement | null;
+    /** Spacer element inside faux scrollbar for setting virtual height */
+    totalHeightEl: HTMLElement | null;
+}
+
+export { }