@toolbox-web/grid 0.2.2 → 0.2.3

package/index.d.ts

@@ -26,7 +26,7 @@ export declare type AggregatorFn = (rows: any[], field: string, column?: 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);
+export declare type AggregatorRef = string | ((rows: unknown[], field: string, column?: unknown) => unknown);
 
 declare type AggregatorRef_2 = string | AggregatorFn;
 
@@ -89,17 +89,17 @@ export declare interface BaseColumnConfig<TRow = any, TValue = any> {
     /** For select/typeahead types - available options */
     options?: Array<{
         label: string;
-        value: any;
+        value: unknown;
     }> | (() => Array<{
         label: string;
-        value: any;
+        value: unknown;
     }>);
     /** For select/typeahead - allow multi select */
     multi?: boolean;
     /** Optional formatter */
     format?: (value: TValue, row: TRow) => string;
     /** Arbitrary extra metadata */
-    meta?: Record<string, any>;
+    meta?: Record<string, unknown>;
 }
 
 /**
@@ -107,7 +107,7 @@ export declare interface BaseColumnConfig<TRow = any, TValue = any> {
  *
  * @template TConfig - Configuration type for the plugin
  */
-export declare abstract class BaseGridPlugin<TConfig = unknown> {
+export declare abstract class BaseGridPlugin<TConfig = unknown> implements GridPlugin {
     /** Unique plugin identifier (derived from class name by default) */
     abstract readonly name: string;
     /** Plugin version - override in subclass if needed */
@@ -403,6 +403,33 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> {
      * ```
      */
     renderRow?(row: any, rowEl: HTMLElement, rowIndex: number): boolean | void;
+    /**
+     * Handle queries from other plugins.
+     * This is the generic mechanism for inter-plugin communication.
+     * Plugins can respond to well-known query types or define their own.
+     *
+     * @param query - The query object with type and context
+     * @returns Query-specific response, or undefined if not handling this query
+     *
+     * @example
+     * ```ts
+     * onPluginQuery(query: PluginQuery): unknown {
+     *   switch (query.type) {
+     *     case PLUGIN_QUERIES.CAN_MOVE_COLUMN:
+     *       // Prevent moving pinned columns
+     *       const column = query.context as ColumnConfig;
+     *       if (column.sticky === 'left' || column.sticky === 'right') {
+     *         return false;
+     *       }
+     *       break;
+     *     case PLUGIN_QUERIES.GET_CONTEXT_MENU_ITEMS:
+     *       const params = query.context as ContextMenuParams;
+     *       return [{ id: 'my-action', label: 'My Action', action: () => {} }];
+     *   }
+     * }
+     * ```
+     */
+    onPluginQuery?(query: PluginQuery): unknown;
     /**
      * Handle keyboard events on the grid.
      * Called when a key is pressed while the grid or a cell has focus.
@@ -546,29 +573,6 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> {
      * ```
      */
     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.
@@ -611,6 +615,34 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> {
      * ```
      */
     applyColumnState?(field: string, state: ColumnState): void;
+    /**
+     * Report horizontal scroll boundary offsets for this plugin.
+     * Plugins that obscure part of the scroll area (e.g., pinned/sticky columns)
+     * should return how much space they occupy on each side.
+     * The keyboard navigation uses this to ensure focused cells are fully visible.
+     *
+     * @param rowEl - The row element (optional, for calculating widths from rendered cells)
+     * @param focusedCell - The currently focused cell element (optional, to determine if scrolling should be skipped)
+     * @returns Object with left/right pixel offsets and optional skipScroll flag, or undefined if plugin has no offsets
+     *
+     * @example
+     * ```ts
+     * getHorizontalScrollOffsets(rowEl?: HTMLElement, focusedCell?: HTMLElement): { left: number; right: number; skipScroll?: boolean } | undefined {
+     *   // Calculate total width of left-pinned columns
+     *   const leftCells = rowEl?.querySelectorAll('.sticky-left') ?? [];
+     *   let left = 0;
+     *   leftCells.forEach(el => { left += (el as HTMLElement).offsetWidth; });
+     *   // Skip scroll if focused cell is pinned (always visible)
+     *   const skipScroll = focusedCell?.classList.contains('sticky-left');
+     *   return { left, right: 0, skipScroll };
+     * }
+     * ```
+     */
+    getHorizontalScrollOffsets?(rowEl?: HTMLElement, focusedCell?: HTMLElement): {
+        left: number;
+        right: number;
+        skipScroll?: boolean;
+    } | undefined;
     /**
      * Register a tool panel for this plugin.
      * Return undefined if plugin has no tool panel.
@@ -678,13 +710,13 @@ export declare interface CellClickEvent {
     originalEvent: MouseEvent;
 }
 
-export declare interface CellCommitDetail<TRow = any> {
+export declare interface CellCommitDetail<TRow = unknown> {
     /** The mutated row after commit. */
     row: TRow;
     /** Field name whose value changed. */
     field: string;
     /** New value stored. */
-    value: any;
+    value: unknown;
     /** Index of the row in current data set. */
     rowIndex: number;
     /** All rows that have at least one committed change (snapshot list). */
@@ -700,7 +732,7 @@ export declare interface CellCommitDetail<TRow = any> {
  */
 declare interface CellContext<T = any> {
     row: T;
-    value: any;
+    value: unknown;
     field: string;
     column: ColumnInternal<T>;
 }
@@ -786,7 +818,7 @@ export declare interface CellRenderContext<TRow = any, TValue = any> {
 export declare type CellRenderer = (ctx: PluginCellRenderContext) => string | HTMLElement;
 
 /** Emitted when the changed rows tracking set is cleared programmatically. */
-export declare interface ChangedRowsResetDetail<TRow = any> {
+export declare interface ChangedRowsResetDetail<TRow = unknown> {
     /** New (empty) changed rows array after reset. */
     rows: TRow[];
     /** Parallel indices (likely empty). */
@@ -801,12 +833,12 @@ export declare interface ColumnConfig<TRow = any> extends BaseColumnConfig<TRow,
     viewRenderer?: ColumnViewRenderer<TRow, any>;
     /** External view spec (lets host app mount any framework component) */
     externalView?: {
-        component: any;
-        props?: Record<string, any>;
+        component: unknown;
+        props?: Record<string, unknown>;
         mount?: (options: {
             placeholder: HTMLElement;
-            context: CellRenderContext<TRow, any>;
-            spec: any;
+            context: CellRenderContext<TRow, unknown>;
+            spec: unknown;
         }) => void | {
             dispose?: () => void;
         };
@@ -838,16 +870,16 @@ export declare interface ColumnEditorContext<TRow = any, TValue = any> {
 }
 
 /** 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) | {
+export declare type ColumnEditorSpec<TRow = unknown, TValue = unknown> = string | ((context: ColumnEditorContext<TRow, TValue>) => HTMLElement | string) | {
     /** Arbitrary component reference (class, function, token) */
-    component: any;
+    component: unknown;
     /** Optional static props passed to mount */
-    props?: Record<string, any>;
+    props?: Record<string, unknown>;
     /** 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;
+        spec: unknown;
     }) => void | {
         dispose?: () => void;
     };
@@ -909,10 +941,10 @@ export declare interface ColumnState {
     sort?: ColumnSortState;
 }
 
-export declare type ColumnViewRenderer<TRow = any, TValue = any> = (ctx: CellRenderContext<TRow, TValue>) => Node | string | void;
+export declare type ColumnViewRenderer<TRow = unknown, TValue = unknown> = (ctx: CellRenderContext<TRow, TValue>) => Node | string | void;
 
 /**
- * Context menu item
+ * Context menu item (used by context-menu plugin query)
  */
 export declare interface ContextMenuItem {
     id: string;
@@ -939,7 +971,7 @@ export declare interface ContextMenuParams {
     isHeader?: boolean;
 }
 
-export declare type DataGridCustomEvent<K extends keyof DataGridEventMap<any>, TRow = any> = CustomEvent<DataGridEventMap<TRow>[K]>;
+export declare type DataGridCustomEvent<K extends keyof DataGridEventMap<unknown>, TRow = unknown> = CustomEvent<DataGridEventMap<TRow>[K]>;
 
 export declare class DataGridElement<T = any> extends HTMLElement implements InternalGrid<T> {
     #private;
@@ -1023,7 +1055,6 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
     emitSortChange(detail: SortChangeDetail): void;
     emitColumnResize(detail: ColumnResizeDetail): void;
     emitActivateCell(detail: ActivateCellDetail): void;
-    updateTemplate(): void;
     findHeaderRow(): HTMLElement;
     findRenderedRowElement(rowIndex: number): HTMLElement | null;
     /**
@@ -1041,6 +1072,26 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * Returns true if any plugin handled the event.
      */
     dispatchKeyDown(event: KeyboardEvent): boolean;
+    /**
+     * Get horizontal scroll boundary offsets from plugins.
+     * Used by keyboard navigation to ensure focused cells are fully visible
+     * when plugins like pinned columns obscure part of the scroll area.
+     */
+    getHorizontalScrollOffsets(rowEl?: HTMLElement, focusedCell?: HTMLElement): {
+        left: number;
+        right: number;
+        skipScroll?: boolean;
+    };
+    /**
+     * Query all plugins with a generic query and collect responses.
+     * This enables inter-plugin communication without the core knowing plugin-specific concepts.
+     *
+     * @example
+     * // Check if any plugin vetoes moving a column
+     * const responses = grid.queryPlugins<boolean>({ type: PLUGIN_QUERIES.CAN_MOVE_COLUMN, context: column });
+     * const canMove = !responses.includes(false);
+     */
+    queryPlugins<T>(query: PluginQuery): T[];
     get changedRows(): T[];
     get changedRowIndices(): number[];
     resetChangedRows(silent?: boolean): Promise<void>;
@@ -1122,76 +1173,42 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * Clears all user modifications (order, width, visibility, sort).
      */
     resetColumnState(): void;
-    /**
-     * Check if the tool panel is currently open.
-     */
+    /** Check if the tool panel is currently open. */
     get isToolPanelOpen(): boolean;
     /**
      * Get the currently active tool panel ID, or null if none is open.
      * @deprecated Use isToolPanelOpen and expandedToolPanelSections instead.
      */
     get activeToolPanel(): string | null;
-    /**
-     * Get the IDs of expanded accordion sections.
-     */
+    /** Get the IDs of expanded accordion sections. */
     get expandedToolPanelSections(): string[];
-    /**
-     * Open the tool panel (accordion view with all registered panels).
-     */
+    /** Open the tool panel (accordion view with all registered panels). */
     openToolPanel(): void;
-    /**
-     * Close the tool panel.
-     */
+    /** Close the tool panel. */
     closeToolPanel(): void;
-    /**
-     * Toggle the tool panel open/closed.
-     */
+    /** Toggle the tool panel open/closed. */
     toggleToolPanel(): void;
-    /**
-     * Toggle an accordion section expanded/collapsed.
-     * Only one section can be expanded at a time (exclusive accordion).
-     * When there's only one panel, toggling is disabled (always expanded).
-     */
+    /** Toggle an accordion section expanded/collapsed. */
     toggleToolPanelSection(sectionId: string): void;
-    /**
-     * Get registered tool panel definitions.
-     */
+    /** Get registered tool panel definitions. */
     getToolPanels(): ToolPanelDefinition[];
-    /**
-     * Register a custom tool panel (without creating a plugin).
-     */
+    /** Register a custom tool panel (without creating a plugin). */
     registerToolPanel(panel: ToolPanelDefinition): void;
-    /**
-     * Unregister a custom tool panel.
-     */
+    /** Unregister a custom tool panel. */
     unregisterToolPanel(panelId: string): void;
-    /**
-     * Get registered header content definitions.
-     */
+    /** Get registered header content definitions. */
     getHeaderContents(): HeaderContentDefinition[];
-    /**
-     * Register custom header content (without creating a plugin).
-     */
+    /** Register custom header content (without creating a plugin). */
     registerHeaderContent(content: HeaderContentDefinition): void;
-    /**
-     * Unregister custom header content.
-     */
+    /** Unregister custom header content. */
     unregisterHeaderContent(contentId: string): void;
-    /**
-     * Get all registered toolbar buttons.
-     */
+    /** Get all registered toolbar buttons. */
     getToolbarButtons(): ToolbarButtonInfo[];
-    /**
-     * Register a custom toolbar button programmatically.
-     */
+    /** Register a custom toolbar button programmatically. */
     registerToolbarButton(button: ToolbarButtonConfig): void;
-    /**
-     * Unregister a custom toolbar button.
-     */
+    /** Unregister a custom toolbar button. */
     unregisterToolbarButton(buttonId: string): void;
-    /**
-     * Enable/disable a toolbar button by ID.
-     */
+    /** Enable/disable a toolbar button by ID. */
     setToolbarButtonDisabled(buttonId: string, disabled: boolean): void;
     /**
      * Re-parse light DOM shell elements and refresh shell header.
@@ -1211,7 +1228,7 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
 export declare interface DataGridElementInterface extends PublicGrid, HTMLElement {
 }
 
-export declare interface DataGridEventMap<TRow = any> {
+export declare interface DataGridEventMap<TRow = unknown> {
     'cell-commit': CellCommitDetail<TRow>;
     'row-commit': RowCommitDetail<TRow>;
     'changed-rows-reset': ChangedRowsResetDetail<TRow>;
@@ -1261,7 +1278,7 @@ export declare interface EditAction {
  * Internal editor execution context extending the generic cell context with commit helpers.
  */
 declare interface EditorExecContext<T = any> extends CellContext<T> {
-    commit: (newValue: any) => void;
+    commit: (newValue: unknown) => void;
     cancel: () => void;
 }
 
@@ -1291,27 +1308,27 @@ export declare interface ExportParams {
     processHeader?: (header: string, field: string) => string;
 }
 
-export declare interface ExternalMountEditorDetail<TRow = any> {
+export declare interface ExternalMountEditorDetail<TRow = unknown> {
     placeholder: HTMLElement;
-    spec: any;
+    spec: unknown;
     context: {
         row: TRow;
-        value: any;
+        value: unknown;
         field: string;
-        column: any;
-        commit: (v: any) => void;
+        column: unknown;
+        commit: (v: unknown) => void;
         cancel: () => void;
     };
 }
 
-export declare interface ExternalMountViewDetail<TRow = any> {
+export declare interface ExternalMountViewDetail<TRow = unknown> {
     placeholder: HTMLElement;
-    spec: any;
+    spec: unknown;
     context: {
         row: TRow;
-        value: any;
+        value: unknown;
         field: string;
-        column: any;
+        column: unknown;
     };
 }
 
@@ -1411,6 +1428,10 @@ export declare function getValueAggregator(aggFunc: string): ValueAggregatorFn;
 /**
  * CSS class names used in the grid's shadow DOM.
  * Use these when adding/removing classes or querying elements.
+ *
+ * Classes are organized by:
+ * - Core: Used by the grid core for structure and basic functionality
+ * - Shared: Used by multiple features/plugins, styled by core CSS
  */
 export declare const GridClasses: {
     readonly ROOT: "tbw-grid-root";
@@ -1496,6 +1517,27 @@ export declare interface GridConfig<TRow = any> {
     fitMode?: FitMode;
     /** Edit activation mode ('click' | 'dblclick'). Can also be set via `editOn` prop. */
     editOn?: string;
+    /**
+     * Row height in pixels for virtualization calculations.
+     * The virtualization system assumes uniform row heights for performance.
+     *
+     * If not specified, the grid measures the first rendered row's height,
+     * which respects the CSS variable `--tbw-row-height` set by themes.
+     *
+     * Set this explicitly when:
+     * - Row content may wrap to multiple lines (also set `--tbw-cell-white-space: normal`)
+     * - Using custom row templates with variable content
+     * - You want to override theme-defined row height
+     *
+     * @default Auto-measured from first row (respects --tbw-row-height CSS variable)
+     *
+     * @example
+     * ```ts
+     * // Fixed height for rows that may wrap to 2 lines
+     * gridConfig = { rowHeight: 56 };
+     * ```
+     */
+    rowHeight?: number;
     /**
      * Array of plugin instances.
      * Each plugin is instantiated with its configuration and attached to this grid.
@@ -1509,7 +1551,7 @@ export declare interface GridConfig<TRow = any> {
      * ]
      * ```
      */
-    plugins?: any[];
+    plugins?: GridPlugin[];
     /**
      * Saved column state to restore on initialization.
      * Includes order, width, visibility, sort, and plugin-contributed state.
@@ -1611,6 +1653,20 @@ export declare interface GridIcons {
     toolPanel?: IconValue;
 }
 
+/**
+ * Minimal plugin interface for type-checking.
+ * This interface is defined here to avoid circular imports with BaseGridPlugin.
+ * All plugins must satisfy this shape (BaseGridPlugin implements it).
+ */
+export declare interface GridPlugin {
+    /** Unique plugin identifier */
+    readonly name: string;
+    /** Plugin version */
+    readonly version: string;
+    /** CSS styles to inject into grid's shadow DOM */
+    readonly styles?: string;
+}
+
 /**
  * Common CSS selectors for querying grid elements.
  * Built from the class constants for consistency.
@@ -1705,7 +1761,7 @@ export declare type HeaderRenderer = (ctx: PluginHeaderRenderContext) => string
 export declare type IconValue = string | HTMLElement;
 
 /** Result of automatic column inference from sample rows. */
-export declare interface InferredColumnResult<TRow = any> {
+export declare interface InferredColumnResult<TRow = unknown> {
     columns: ColumnConfigMap<TRow>;
     typeMap: Record<string, PrimitiveColumnType>;
 }
@@ -1737,7 +1793,7 @@ declare interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     focusRow: number;
     focusCol: number;
     activeEditRows: number;
-    rowEditSnapshots: Map<number, any>;
+    rowEditSnapshots: Map<number, T>;
     _changedRowIndices: Set<number>;
     changedRows?: T[];
     changedRowIndices?: number[];
@@ -1754,6 +1810,14 @@ declare interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     dispatchHeaderClick?: (event: MouseEvent, colIndex: number, headerEl: HTMLElement) => boolean;
     /** Dispatch keydown to plugin system, returns true if handled */
     dispatchKeyDown?: (event: KeyboardEvent) => boolean;
+    /** Get horizontal scroll boundary offsets from plugins (e.g., pinned columns) */
+    getHorizontalScrollOffsets?: (rowEl?: HTMLElement, focusedCell?: HTMLElement) => {
+        left: number;
+        right: number;
+        skipScroll?: boolean;
+    };
+    /** Query all plugins with a generic query and collect responses */
+    queryPlugins?: <T>(query: PluginQuery) => T[];
     /** Request emission of column-state-change event (debounced) */
     requestStateChange?: () => void;
 }
@@ -1850,6 +1914,17 @@ export declare interface PivotValueField {
     header?: string;
 }
 
+/**
+ * Well-known plugin query types.
+ * Plugins can define additional query types beyond these.
+ */
+export declare const PLUGIN_QUERIES: {
+    /** Ask if a column can be moved. Context: ColumnConfig. Response: boolean | undefined */
+    readonly CAN_MOVE_COLUMN: "canMoveColumn";
+    /** Get context menu items. Context: ContextMenuParams. Response: ContextMenuItem[] */
+    readonly GET_CONTEXT_MENU_ITEMS: "getContextMenuItems";
+};
+
 /**
  * Cell render context for plugin cell renderers.
  * Provides full context including position and editing state.
@@ -2008,6 +2083,16 @@ export declare class PluginManager {
      * Returns true if any plugin handled the row.
      */
     renderRow(row: any, rowEl: HTMLElement, rowIndex: number): boolean;
+    /**
+     * Query all plugins with a generic query and collect responses.
+     * This enables inter-plugin communication without the core knowing plugin-specific concepts.
+     *
+     * Common query types are defined in PLUGIN_QUERIES, but plugins can define their own.
+     *
+     * @param query - The query object containing type and context
+     * @returns Array of non-undefined responses from plugins
+     */
+    queryPlugins<T>(query: PluginQuery): T[];
     /**
      * Execute onKeyDown hook on all plugins.
      * Returns true if any plugin handled the event.
@@ -2048,9 +2133,18 @@ export declare class PluginManager {
      */
     onCellMouseUp(event: CellMouseEvent): boolean;
     /**
-     * Collect context menu items from all plugins.
-     */
-    getContextMenuItems(params: ContextMenuParams): ContextMenuItem[];
+     * Collect horizontal scroll boundary offsets from all plugins.
+     * Combines offsets from all plugins that report them.
+     *
+     * @param rowEl - The row element (optional, for calculating widths from rendered cells)
+     * @param focusedCell - The currently focused cell element (optional, to determine if scrolling should be skipped)
+     * @returns Combined left and right pixel offsets, plus skipScroll if any plugin requests it
+     */
+    getHorizontalScrollOffsets(rowEl?: HTMLElement, focusedCell?: HTMLElement): {
+        left: number;
+        right: number;
+        skipScroll?: boolean;
+    };
     /**
      * Collect tool panels from all plugins.
      * Returns panels sorted by order (ascending).
@@ -2069,6 +2163,18 @@ export declare class PluginManager {
     }[];
 }
 
+/**
+ * Generic plugin query for inter-plugin communication.
+ * Plugins can define their own query types as string constants
+ * and respond to queries from other plugins.
+ */
+export declare interface PluginQuery<T = unknown> {
+    /** Query type identifier (e.g., 'canMoveColumn', 'getContextMenuItems') */
+    type: string;
+    /** Query-specific context/parameters */
+    context: T;
+}
+
 export declare type PrimitiveColumnType = 'number' | 'string' | 'date' | 'boolean' | 'select' | 'typeahead';
 
 /**
@@ -2131,7 +2237,7 @@ export declare interface RowClickEvent {
 }
 
 /** Detail payload for a committed row edit (may or may not include changes). */
-export declare interface RowCommitDetail<TRow = any> {
+export declare interface RowCommitDetail<TRow = unknown> {
     /** Row index that lost edit focus. */
     rowIndex: number;
     /** Row object reference. */
@@ -2152,7 +2258,7 @@ 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;
+    formatLabel?: (value: unknown, 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. */