@toolbox-web/grid 1.24.1 → 1.25.0

package/lib/core/internal/rows.d.ts

@@ -1,4 +1,4 @@
-import { ColumnInternal, ColumnViewRenderer, InternalGrid } from '../types';
+import { ColumnInternal, ColumnViewRenderer, GridHost, InternalGrid } from '../types';
 /** Callback type for plugin row rendering hook */
 export type RenderRowHook = (row: any, rowEl: HTMLElement, rowIndex: number) => boolean;
 /**
@@ -39,15 +39,14 @@ export declare function invalidateCellCache(grid: InternalGrid): void;
  * @param renderRowHook - Optional callback that plugins can use to render custom rows (e.g., group rows).
  *                        If it returns true, default rendering is skipped for that row.
  */
-export declare function renderVisibleRows(grid: InternalGrid, start: number, end: number, epoch?: number, renderRowHook?: RenderRowHook): void;
+export declare function renderVisibleRows(grid: GridHost, start: number, end: number, epoch?: number, renderRowHook?: RenderRowHook): void;
 /**
  * Full reconstruction of a row's set of cells including templated, external view, and formatted content.
  * Attaches event handlers for editing and accessibility per cell.
  */
-export declare function renderInlineRow(grid: InternalGrid, rowEl: HTMLElement, rowData: any, rowIndex: number): void;
+export declare function renderInlineRow(grid: GridHost, rowEl: HTMLElement, rowData: any, rowIndex: number): void;
 /**
  * Handle click / double click interaction to focus cells.
  * Edit triggering is handled by EditingPlugin via onCellClick hook.
  */
-export declare function handleRowClick(grid: InternalGrid, e: MouseEvent, rowEl: HTMLElement): void;
-//# sourceMappingURL=rows.d.ts.map
+export declare function handleRowClick(grid: GridHost, e: MouseEvent, rowEl: HTMLElement): void;

package/lib/core/internal/sanitize.d.ts

@@ -18,4 +18,3 @@ export declare function sanitizeHTML(html: string): string;
 export declare function evalTemplateString(raw: string, ctx: EvalContext): string;
 export declare function finalCellScrub(cell: HTMLElement): void;
 export declare function compileTemplate(raw: string): CompiledViewFunction<any>;
-//# sourceMappingURL=sanitize.d.ts.map

package/lib/core/internal/shell.d.ts

@@ -1,4 +1,4 @@
-import { HeaderContentDefinition, IconValue, ShellConfig, ToolbarContentDefinition, ToolPanelDefinition } from '../types';
+import { HeaderContentDefinition, IconValue, InternalGrid, ShellConfig, ToolbarContentDefinition, ToolPanelDefinition } from '../types';
 /**
  * State for managing shell UI.
  *
@@ -25,6 +25,8 @@ export interface ShellState {
     lightDomToolbarContentIds: Set<string>;
     /** IDs of tool panels registered via registerToolPanel API */
     apiToolPanelIds: Set<string>;
+    /** IDs of header content registered via registerHeaderContent API */
+    apiHeaderContentIds: Set<string>;
     /** Whether the tool panel sidebar is open */
     isPanelOpen: boolean;
     /** Which accordion sections are expanded (by panel ID) */
@@ -206,33 +208,14 @@ export declare function updateToolbarActiveStates(renderRoot: Element, state: Sh
 export declare function updatePanelState(renderRoot: Element, state: ShellState): void;
 /**
  * Prepare shell state for a full re-render.
- * Runs cleanup functions so content (like toolbar buttons) can be restored
- * to their original containers and moved to new slots after re-render.
+ * Runs cleanup functions so content (toolbar buttons, panels, headers)
+ * can be restored to their original containers and re-rendered into new DOM.
  */
 export declare function prepareForRerender(state: ShellState): void;
 /**
  * Cleanup all shell state when grid disconnects.
  */
 export declare function cleanupShellState(state: ShellState): void;
-/**
- * Callbacks for ShellController to communicate with the grid.
- * This interface decouples the controller from grid internals.
- */
-export interface ShellControllerCallbacks {
-    /** Get the render root for DOM queries (the grid element) */
-    getShadow: () => Element;
-    /** Get the current shell config */
-    getShellConfig: () => ShellConfig | undefined;
-    /** Get accordion expand/collapse icons */
-    getAccordionIcons: () => {
-        expand: IconValue;
-        collapse: IconValue;
-    };
-    /** Emit an event from the grid */
-    emit: (eventName: string, detail: unknown) => void;
-    /** Refresh the shell header (re-parse light DOM and re-render) */
-    refreshShellHeader: () => void;
-}
 /**
  * Controller interface for managing shell/tool panel behavior.
  */
@@ -278,12 +261,12 @@ export interface ShellController {
  * Create a ShellController instance.
  * The controller encapsulates all tool panel orchestration logic.
  */
-export declare function createShellController(state: ShellState, callbacks: ShellControllerCallbacks): ShellController;
+export declare function createShellController(state: ShellState, grid: InternalGrid): ShellController;
 /**
  * Core grid content HTML template.
  * Uses faux scrollbar pattern for smooth virtualized scrolling.
  */
-export declare const GRID_CONTENT_HTML = "\n  <div class=\"tbw-scroll-area\">\n    <div class=\"rows-body-wrapper\">\n      <div class=\"rows-body\" role=\"grid\">\n        <div class=\"header\" role=\"rowgroup\">\n          <div class=\"header-row\" role=\"row\" part=\"header-row\"></div>\n        </div>\n        <div class=\"rows-container\" role=\"presentation\">\n          <div class=\"rows-viewport\" role=\"presentation\">\n            <div class=\"rows\"></div>\n          </div>\n        </div>\n      </div>\n    </div>\n  </div>\n  <div class=\"faux-vscroll\">\n    <div class=\"faux-vscroll-spacer\"></div>\n  </div>\n";
+export declare const GRID_CONTENT_HTML = "\n  <div class=\"tbw-scroll-area\">\n    <div class=\"rows-body-wrapper\">\n      <div class=\"rows-body\" role=\"grid\">\n        <div class=\"header\" role=\"rowgroup\">\n          <div class=\"header-row\" role=\"row\" part=\"header-row\"></div>\n        </div>\n        <div class=\"rows-container\" role=\"presentation\">\n          <div class=\"rows-viewport\" role=\"presentation\">\n            <div class=\"rows\"></div>\n          </div>\n        </div>\n      </div>\n    </div>\n  </div>\n  <div class=\"faux-vscroll\">\n    <div class=\"faux-vscroll-spacer\"></div>\n  </div>\n  <div class=\"tbw-sr-only\" aria-live=\"polite\" aria-atomic=\"true\"></div>\n";
 /**
  * Build the complete grid DOM structure using direct DOM construction.
  * This is 2-3x faster than innerHTML for initial render.
@@ -302,4 +285,3 @@ export declare function buildGridDOMIntoElement(renderRoot: Element, shellConfig
     expand?: IconValue;
     collapse?: IconValue;
 }): boolean;
-//# sourceMappingURL=shell.d.ts.map

package/lib/core/internal/sorting.d.ts

@@ -1,4 +1,4 @@
-import { ColumnConfig, InternalGrid, SortState } from '../types';
+import { ColumnConfig, GridHost, InternalGrid, SortState } from '../types';
 /**
  * Default comparator for sorting values.
  * Handles nulls (pushed to end), numbers, and string fallback.
@@ -13,7 +13,7 @@ export declare function builtInSort<T>(rows: T[], sortState: SortState, columns:
  * Cycle sort state for a column: none -> ascending -> descending -> none.
  * Restores original row order when clearing sort.
  */
-export declare function toggleSort(grid: InternalGrid, col: ColumnConfig<any>): void;
+export declare function toggleSort(grid: GridHost, col: ColumnConfig<any>): void;
 /**
  * Re-apply the current core sort to rows during #rebuildRowModel.
  * Updates __originalOrder so "clear sort" restores the current dataset.
@@ -26,5 +26,4 @@ export declare function reapplyCoreSort<T>(grid: InternalGrid<T>, rows: T[]): T[
  * Uses custom sortHandler from gridConfig if provided, otherwise uses built-in sorting.
  * Supports both sync and async handlers (for server-side sorting).
  */
-export declare function applySort(grid: InternalGrid, col: ColumnConfig<any>, dir: 1 | -1): void;
-//# sourceMappingURL=sorting.d.ts.map
+export declare function applySort(grid: GridHost, col: ColumnConfig<any>, dir: 1 | -1): void;

package/lib/core/internal/style-injector.d.ts

@@ -32,4 +32,3 @@ export declare function injectStyles(inlineStyles: string): Promise<void>;
  * @internal
  */
 export declare function _resetForTesting(): void;
-//# sourceMappingURL=style-injector.d.ts.map

package/lib/core/internal/touch-scroll.d.ts

@@ -1,20 +1,35 @@
 /**
  * Touch scrolling controller for mobile devices.
  *
- * Handles touch events for scrolling with momentum physics.
- * Supports both vertical (faux scrollbar) and horizontal (scroll area) scrolling.
+ * Uses pointer events with setPointerCapture to ensure events are delivered
+ * directly to the grid element, even when DOM virtualization replaces the
+ * original touch target element mid-gesture.
+ *
+ * Without pointer capture, touch events are dispatched to the original target
+ * element (e.g., a cell or card). When virtualization recycles that element's
+ * content, the target is removed from the DOM and subsequent touchmove/touchend
+ * events are lost — causing scrolling to stop after ~2 rows.
+ *
+ * setPointerCapture routes all events for a pointer ID directly to the capture
+ * element (.tbw-grid-content), bypassing target resolution entirely.
+ *
+ * Uses incremental deltas (frame-to-frame) rather than absolute offsets from
+ * the gesture start, which is more robust when virtualized content height
+ * changes during scrolling (e.g., responsive card mode with variable-height rows).
  */
 export interface TouchScrollState {
     startY: number | null;
     startX: number | null;
-    scrollTop: number | null;
-    scrollLeft: number | null;
     lastY: number | null;
     lastX: number | null;
     lastTime: number | null;
     velocityY: number;
     velocityX: number;
     momentumRaf: number;
+    /** Once we start scrolling the grid, lock until gesture ends to prevent browser takeover */
+    locked: boolean;
+    /** Active pointer ID for setPointerCapture tracking (null = no active gesture) */
+    activePointerId: number | null;
 }
 export interface TouchScrollElements {
     fauxScrollbar: HTMLElement;
@@ -33,22 +48,26 @@ export declare function resetTouchState(state: TouchScrollState): void;
  */
 export declare function cancelMomentum(state: TouchScrollState): void;
 /**
- * Handle touchstart event.
+ * Handle gesture start (from pointerdown).
  */
-export declare function handleTouchStart(e: TouchEvent, state: TouchScrollState, elements: TouchScrollElements): void;
+export declare function handleTouchStart(clientX: number, clientY: number, state: TouchScrollState): void;
 /**
- * Handle touchmove event.
- * Returns true if the event should be prevented (grid scrolled).
+ * Handle gesture move (from pointermove).
+ * Uses incremental deltas (from previous position) for robustness.
+ * Returns true if the event should be prevented (grid is handling scroll).
  */
-export declare function handleTouchMove(e: TouchEvent, state: TouchScrollState, elements: TouchScrollElements): boolean;
+export declare function handleTouchMove(clientX: number, clientY: number, state: TouchScrollState, elements: TouchScrollElements): boolean;
 /**
  * Handle touchend event.
  * Starts momentum scrolling if velocity is significant.
  */
 export declare function handleTouchEnd(state: TouchScrollState, elements: TouchScrollElements): void;
 /**
- * Set up touch scroll event listeners on the grid content element.
- * Returns a cleanup function that removes all listeners.
+ * Set up pointer event listeners on the grid content element for touch scrolling.
+ *
+ * Uses pointer events + setPointerCapture instead of touch events because
+ * DOM virtualization can destroy the original touch target mid-gesture,
+ * causing touch events to stop being delivered. Pointer capture routes
+ * all events directly to the grid element regardless of DOM changes.
  */
 export declare function setupTouchScrollListeners(gridContentEl: HTMLElement, state: TouchScrollState, elements: TouchScrollElements, signal: AbortSignal): void;
-//# sourceMappingURL=touch-scroll.d.ts.map

package/lib/core/internal/utils.d.ts

@@ -4,6 +4,14 @@
  * Used to show warnings only in development.
  */
 export declare function isDevelopment(): boolean;
+/**
+ * Build the `[tbw-grid]` or `[tbw-grid#my-id]` log prefix.
+ * Pass `pluginName` for a scoped prefix like `[tbw-grid:SelectionPlugin]`.
+ *
+ * @param gridId - The grid element's `id` attribute (optional)
+ * @param pluginName - Plugin display name to include (optional)
+ */
+export declare function gridPrefix(gridId?: string, pluginName?: string): string;
 /**
  * Generate accessible HTML for a boolean cell.
  * Uses role="checkbox" with proper aria attributes.
@@ -77,4 +85,3 @@ export declare function isRTL(element: Element): boolean;
  * ```
  */
 export declare function resolveInlinePosition(position: 'left' | 'right' | 'start' | 'end', direction: TextDirection): 'left' | 'right';
-//# sourceMappingURL=utils.d.ts.map

package/lib/core/internal/validate-config.d.ts

@@ -7,7 +7,7 @@ import { GridConfig } from '../types';
  * @param plugins - The array of loaded plugins
  * @throws Error if a plugin-owned property is used without the plugin
  */
-export declare function validatePluginProperties<T>(config: GridConfig<T>, plugins: readonly BaseGridPlugin[]): void;
+export declare function validatePluginProperties<T>(config: GridConfig<T>, plugins: readonly BaseGridPlugin[], gridId?: string): void;
 /**
  * Validate plugin configuration rules declared in manifests.
  * Called after plugins are attached to check for invalid/conflicting configurations.
@@ -17,7 +17,7 @@ export declare function validatePluginProperties<T>(config: GridConfig<T>, plugi
  *
  * @param plugins - The array of attached plugins (with config already merged)
  */
-export declare function validatePluginConfigRules(plugins: readonly BaseGridPlugin[]): void;
+export declare function validatePluginConfigRules(plugins: readonly BaseGridPlugin[], gridId?: string): void;
 /**
  * Validate plugin-to-plugin dependencies.
  * Called by PluginManager when attaching a new plugin.
@@ -31,7 +31,7 @@ export declare function validatePluginConfigRules(plugins: readonly BaseGridPlug
  * @param loadedPlugins - The array of already-loaded plugins
  * @throws Error if a required dependency is missing
  */
-export declare function validatePluginDependencies(plugin: BaseGridPlugin, loadedPlugins: readonly BaseGridPlugin[]): void;
+export declare function validatePluginDependencies(plugin: BaseGridPlugin, loadedPlugins: readonly BaseGridPlugin[], gridId?: string): void;
 /**
  * Validate that no incompatible plugins are loaded together.
  * Called after all plugins are attached to the grid.
@@ -41,5 +41,4 @@ export declare function validatePluginDependencies(plugin: BaseGridPlugin, loade
  *
  * @param plugins - All attached plugins
  */
-export declare function validatePluginIncompatibilities(plugins: readonly BaseGridPlugin[]): void;
-//# sourceMappingURL=validate-config.d.ts.map
+export declare function validatePluginIncompatibilities(plugins: readonly BaseGridPlugin[], gridId?: string): void;

package/lib/core/internal/virtualization-manager.d.ts

@@ -0,0 +1,48 @@
+import { InternalGrid, VirtualState } from '../types';
+export declare class VirtualizationManager<T = any> {
+    #private;
+    readonly state: VirtualState;
+    constructor(grid: InternalGrid<T>, initialState?: Partial<VirtualState>);
+    /**
+     * Update cached viewport and faux scrollbar geometry.
+     * Called by ResizeObserver and on force-refresh to avoid forced layout reads during scroll.
+     */
+    updateCachedGeometry(): void;
+    /**
+     * Calculate total height for the faux scrollbar spacer element.
+     * Used by both bypass and virtualized rendering paths to ensure consistent scroll behavior.
+     *
+     * @param totalRows - Total number of rows to calculate height for
+     * @param forceRead - When true, reads fresh geometry from DOM (used after structural changes).
+     *   When false, uses cached values from ResizeObserver to avoid forced synchronous layout.
+     */
+    calculateTotalSpacerHeight(totalRows: number, forceRead?: boolean): number;
+    /**
+     * Initialize or rebuild the position cache for variable row heights.
+     * Called when rows change or variable heights mode is enabled.
+     */
+    initializePositionCache(): void;
+    /**
+     * Invalidate a row's height in the position cache.
+     * Call this when a plugin changes a row's height (e.g., expanding/collapsing a detail panel).
+     * Updates the position cache incrementally O(1) + offset recalc O(k) without a full rebuild.
+     *
+     * @param rowIndex - Index of the row whose height changed
+     * @param newHeight - Optional new height. If not provided, queries plugins for height.
+     */
+    invalidateRowHeight(rowIndex: number, newHeight?: number): void;
+    /**
+     * Measure rendered row heights and update position cache.
+     * Called after rows are rendered to capture actual DOM heights.
+     * Only runs when variable heights mode is enabled.
+     */
+    measureRenderedRowHeights(start: number, end: number): void;
+    /**
+     * Core virtualization routine. Chooses between bypass (small datasets), grouped window rendering,
+     * or standard row window rendering.
+     * @param force - Whether to force a full refresh (not just scroll update)
+     * @param skipAfterRender - When true, skip calling afterRender (used by scheduler which calls it separately)
+     * @returns Whether the visible row window changed (start/end differ from previous)
+     */
+    refreshVirtualWindow(force?: boolean, skipAfterRender?: boolean): boolean;
+}

package/lib/core/internal/virtualization.d.ts

@@ -217,4 +217,3 @@ export declare function computeVirtualWindow(params: VirtualWindowParams): Virtu
  * @returns True if virtualization should be bypassed
  */
 export declare function shouldBypassVirtualization(totalRows: number, threshold: number): boolean;
-//# sourceMappingURL=virtualization.d.ts.map

package/lib/core/plugin/base-plugin.d.ts

@@ -1,7 +1,7 @@
 import { ColumnConfig, ColumnState, GridPlugin, HeaderContentDefinition, IconValue, PluginNameMap, ToolPanelDefinition, DEFAULT_GRID_ICONS } from '../types';
 import { AfterCellRenderContext, AfterRowRenderContext, CellClickEvent, CellEditor, CellMouseEvent, CellRenderer, GridElementRef, HeaderClickEvent, HeaderRenderer, PluginQuery, RowClickEvent, ScrollEvent } from './types';
 export { PLUGIN_QUERIES } from './types';
-export type { AfterCellRenderContext, AfterRowRenderContext, CellClickEvent, CellCoords, CellEditor, CellMouseEvent, CellRenderer, ContextMenuItem, ContextMenuParams, GridElementRef, HeaderClickEvent, HeaderRenderer, KeyboardModifiers, PluginCellRenderContext, PluginQuery, RowClickEvent, ScrollEvent, } from './types';
+export type { AfterCellRenderContext, AfterRowRenderContext, CellClickEvent, CellCoords, CellEditor, CellMouseEvent, CellRenderer, ContextMenuItem, ContextMenuParams, GridElementRef, HeaderClickEvent, HeaderRenderer, KeyboardModifiers, PluginCellRenderContext, PluginQuery, RowClickEvent, ScrollEvent } from './types';
 /**
  * Grid element interface for plugins.
  * Extends GridElementRef with plugin-specific methods.
@@ -946,7 +946,7 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> implements GridP
      *   }
      * }
      * ```
-     * @deprecated Use `handleQuery` instead for new plugins.
+     * @deprecated Use `handleQuery` instead for new plugins. Will be removed in v2.
      */
     onPluginQuery?(query: PluginQuery): unknown;
     /**
@@ -1244,4 +1244,3 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> implements GridP
      */
     getHeaderContent?(): HeaderContentDefinition | undefined;
 }
-//# sourceMappingURL=base-plugin.d.ts.map

package/lib/core/plugin/expander-column.d.ts

@@ -48,4 +48,3 @@ export declare function createExpanderContainer(expanded: boolean, pluginClass:
  * Plugins should include this in their styles to ensure consistent appearance.
  */
 export declare const EXPANDER_COLUMN_STYLES = "\n/* Expander column data cells - always first, borderless right edge */\n.cell[data-field=\"__tbw_expander\"] {\n  border-right: none !important;\n  padding: 0;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n}\n\n/* Expander column header - completely hidden, no content, no border, no width contribution */\n.header-row .cell[data-field=\"__tbw_expander\"] {\n  visibility: hidden;\n  border: none !important;\n  padding: 0;\n  overflow: hidden;\n}\n\n/* The column after the expander should visually extend into the expander header space */\n.header-row .cell[data-field=\"__tbw_expander\"] + .cell {\n  /* Pull left to cover the hidden expander header */\n  margin-left: -32px;\n  padding-left: calc(var(--tbw-cell-padding, 8px) + 32px);\n}\n\n/* Expander cell contents */\n.expander-cell {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 100%;\n  height: 100%;\n  cursor: pointer;\n}\n";
-//# sourceMappingURL=expander-column.d.ts.map

package/lib/core/plugin/index.d.ts

@@ -9,4 +9,3 @@ export type { AfterCellRenderContext, AfterRowRenderContext, CellClickEvent, Cel
 export { PluginManager } from './plugin-manager';
 export type { EventDefinition, HookName, PluginConfigRule, PluginDependency, PluginIncompatibility, PluginManifest, PluginPropertyDefinition, QueryDefinition, } from './base-plugin';
 export type { ColumnConfig } from '../types';
-//# sourceMappingURL=index.d.ts.map

package/lib/core/plugin/plugin-manager.d.ts

@@ -35,6 +35,8 @@ export declare class PluginManager {
     /** Set of plugin constructors that have been warned about deprecated hooks */
     private static deprecationWarned;
     constructor(grid: GridElement);
+    /** Build log prefix: `[tbw-grid]` or `[tbw-grid#my-id]` */
+    private get logPrefix();
     /**
      * Attach all plugins from the config.
      */
@@ -298,4 +300,3 @@ export declare class PluginManager {
         content: NonNullable<ReturnType<NonNullable<BaseGridPlugin['getHeaderContent']>>>;
     }[];
 }
-//# sourceMappingURL=plugin-manager.d.ts.map

package/lib/core/plugin/types.d.ts

@@ -45,7 +45,7 @@ export interface HeaderClickEvent {
     field: string;
     column: ColumnConfig;
     headerEl: HTMLElement;
-    originalEvent: MouseEvent;
+    originalEvent: MouseEvent | KeyboardEvent;
 }
 /**
  * Scroll event
@@ -275,6 +275,12 @@ export interface GridElementRef {
     getAttribute(name: string): string | null;
     /** Remove an attribute from the grid element. */
     removeAttribute(name: string): void;
+    /**
+     * The grid's host HTMLElement.
+     * Use this instead of casting the grid to HTMLElement.
+     * @internal Plugin API
+     */
+    readonly _hostElement: HTMLElement;
     /** Current rows (after plugin processing like grouping, filtering). */
     rows: unknown[];
     /** Original unfiltered/unprocessed rows. */
@@ -466,4 +472,3 @@ export interface GridElementRef {
      */
     invalidateRowHeight(rowIndex: number, newHeight?: number): void;
 }
-//# sourceMappingURL=types.d.ts.map

package/lib/core/styles/index.d.ts

@@ -29,4 +29,3 @@
  */
 export declare const gridStyles: string;
 export default gridStyles;
-//# sourceMappingURL=index.d.ts.map