@toolbox-web/grid 0.0.4 → 0.0.6

package/index.d.ts

@@ -180,6 +180,46 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> {
      * Get the shadow root of the grid.
      */
     protected get shadowRoot(): ShadowRoot | null;
+    /**
+     * Get the disconnect signal for event listener cleanup.
+     * This signal is aborted when the grid disconnects from the DOM.
+     * Use this when adding event listeners that should be cleaned up automatically.
+     *
+     * Best for:
+     * - Document/window-level listeners added in attach()
+     * - Listeners on the grid element itself
+     * - Any listener that should persist across renders
+     *
+     * Not needed for:
+     * - Listeners on elements created in afterRender() (removed with element)
+     *
+     * @example
+     * element.addEventListener('click', handler, { signal: this.disconnectSignal });
+     * document.addEventListener('keydown', handler, { signal: this.disconnectSignal });
+     */
+    protected get disconnectSignal(): AbortSignal;
+    /**
+     * Get the grid-level icons configuration.
+     * Returns merged icons (user config + defaults).
+     */
+    protected get gridIcons(): typeof DEFAULT_GRID_ICONS;
+    /**
+     * Resolve an icon value to string or HTMLElement.
+     * Checks plugin config first, then grid-level icons, then defaults.
+     *
+     * @param iconKey - The icon key in GridIcons (e.g., 'expand', 'collapse')
+     * @param pluginOverride - Optional plugin-level override
+     * @returns The resolved icon value
+     */
+    protected resolveIcon(iconKey: keyof typeof DEFAULT_GRID_ICONS, pluginOverride?: IconValue): IconValue;
+    /**
+     * Set an icon value on an element.
+     * Handles both string (text/HTML) and HTMLElement values.
+     *
+     * @param element - The element to set the icon on
+     * @param icon - The icon value (string or HTMLElement)
+     */
+    protected setIcon(element: HTMLElement, icon: IconValue): void;
     /**
      * Log a warning message.
      */
@@ -277,6 +317,68 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> {
      * ```
      */
     onScrollRender?(): void;
+    /**
+     * Return extra height contributed by this plugin (e.g., expanded detail rows).
+     * Used to adjust scrollbar height calculations for virtualization.
+     *
+     * @returns Total extra height in pixels
+     *
+     * @example
+     * ```ts
+     * getExtraHeight(): number {
+     *   return this.expandedRows.size * this.detailHeight;
+     * }
+     * ```
+     */
+    getExtraHeight?(): number;
+    /**
+     * Return extra height that appears before a given row index.
+     * Used by virtualization to correctly calculate scroll positions when
+     * there's variable height content (like expanded detail rows) above the viewport.
+     *
+     * @param beforeRowIndex - The row index to calculate extra height before
+     * @returns Extra height in pixels that appears before this row
+     *
+     * @example
+     * ```ts
+     * getExtraHeightBefore(beforeRowIndex: number): number {
+     *   let height = 0;
+     *   for (const expandedRowIndex of this.expandedRowIndices) {
+     *     if (expandedRowIndex < beforeRowIndex) {
+     *       height += this.getDetailHeight(expandedRowIndex);
+     *     }
+     *   }
+     *   return height;
+     * }
+     * ```
+     */
+    getExtraHeightBefore?(beforeRowIndex: number): number;
+    /**
+     * Adjust the virtualization start index to render additional rows before the visible range.
+     * Use this when expanded content (like detail rows) needs its parent row to remain rendered
+     * even when the parent row itself has scrolled above the viewport.
+     *
+     * @param start - The calculated start row index
+     * @param scrollTop - The current scroll position
+     * @param rowHeight - The height of a single row
+     * @returns The adjusted start index (lower than or equal to original start)
+     *
+     * @example
+     * ```ts
+     * adjustVirtualStart(start: number, scrollTop: number, rowHeight: number): number {
+     *   // If row 5 is expanded and scrolled partially, keep it rendered
+     *   for (const expandedRowIndex of this.expandedRowIndices) {
+     *     const expandedRowTop = expandedRowIndex * rowHeight;
+     *     const expandedRowBottom = expandedRowTop + rowHeight + this.detailHeight;
+     *     if (expandedRowBottom > scrollTop && expandedRowIndex < start) {
+     *       return expandedRowIndex;
+     *     }
+     *   }
+     *   return start;
+     * }
+     * ```
+     */
+    adjustVirtualStart?(start: number, scrollTop: number, rowHeight: number): number;
     /**
      * Render a custom row, bypassing the default row rendering.
      * Use this for special row types like group headers, detail rows, or footers.
@@ -926,6 +1028,14 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
     get editOn(): string | undefined;
     set editOn(value: string | undefined);
     get effectiveConfig(): GridConfig<T>;
+    /**
+     * Get the disconnect signal for event listener cleanup.
+     * This signal is aborted when the grid disconnects from the DOM.
+     * Plugins and internal code can use this for automatic listener cleanup.
+     * @example
+     * element.addEventListener('click', handler, { signal: this.grid.disconnectSignal });
+     */
+    get disconnectSignal(): AbortSignal;
     constructor();
     /**
      * Get a plugin instance by its class.
@@ -1142,6 +1252,9 @@ export declare interface DataGridEventMap<TRow = any> {
     'column-state-change': GridColumnState;
 }
 
+/** Default icons used when not overridden */
+export declare const DEFAULT_GRID_ICONS: Required<GridIcons>;
+
 export declare type DGEventName = (typeof DGEvents)[keyof typeof DGEvents];
 
 export declare const DGEvents: {
@@ -1445,6 +1558,12 @@ export declare interface GridConfig<TRow = any> {
      * When configured, adds an optional wrapper with title, toolbar, and collapsible side panels.
      */
     shell?: ShellConfig;
+    /**
+     * Grid-wide icon configuration.
+     * Provides consistent icons across all plugins (tree, grouping, sorting, etc.).
+     * Plugins will use these by default but can override with their own config.
+     */
+    icons?: GridIcons;
 }
 
 export declare type GridCSSVar = (typeof GridCSSVars)[keyof typeof GridCSSVars];
@@ -1493,6 +1612,8 @@ export declare interface GridElement {
     rows: any[];
     columns: ColumnConfig[];
     gridConfig: any;
+    /** AbortSignal that is aborted when the grid disconnects from the DOM */
+    disconnectSignal: AbortSignal;
     requestRender(): void;
     requestAfterRender(): void;
     forceLayout(): Promise<void>;
@@ -1501,6 +1622,27 @@ export declare interface GridElement {
     dispatchEvent(event: Event): boolean;
 }
 
+/**
+ * Grid-wide icon configuration.
+ * All icons are optional - sensible defaults are used when not specified.
+ */
+export declare interface GridIcons {
+    /** Expand icon for collapsed items (trees, groups, details). Default: '▶' */
+    expand?: IconValue;
+    /** Collapse icon for expanded items (trees, groups, details). Default: '▼' */
+    collapse?: IconValue;
+    /** Sort ascending indicator. Default: '▲' */
+    sortAsc?: IconValue;
+    /** Sort descending indicator. Default: '▼' */
+    sortDesc?: IconValue;
+    /** Sort neutral/unsorted indicator. Default: '⇅' */
+    sortNone?: IconValue;
+    /** Submenu arrow for context menus. Default: '▶' */
+    submenuArrow?: IconValue;
+    /** Drag handle icon for reordering. Default: '⋮⋮' */
+    dragHandle?: IconValue;
+}
+
 /**
  * Common CSS selectors for querying grid elements.
  * Built from the class constants for consistency.
@@ -1533,7 +1675,7 @@ export declare interface GroupingRowsConfig {
     groupOn?: (row: any) => any[] | any | null | false;
     /** Whether groups are expanded by default (default: false) */
     defaultExpanded?: boolean;
-    /** Custom group row renderer */
+    /** Custom group row renderer - takes full control of group row rendering */
     groupRowRenderer?: (params: GroupRowRenderParams) => HTMLElement | string | void;
     /** Show row count in group headers (default: true) */
     showRowCount?: boolean;
@@ -1593,6 +1735,9 @@ export declare interface HeaderContentDefinition {
  */
 export declare type HeaderRenderer = (ctx: PluginHeaderRenderContext) => string | HTMLElement;
 
+/** Icon value - can be a string (text/HTML) or HTMLElement */
+export declare type IconValue = string | HTMLElement;
+
 /** Result of automatic column inference from sample rows. */
 export declare interface InferredColumnResult<TRow = any> {
     columns: ColumnConfigMap<TRow>;
@@ -1865,6 +2010,21 @@ export declare class PluginManager {
      * Called after scroll-triggered row rendering for lightweight visual state updates.
      */
     onScrollRender(): void;
+    /**
+     * Get total extra height contributed by plugins (e.g., expanded detail rows).
+     * Used to adjust scrollbar height calculations.
+     */
+    getExtraHeight(): number;
+    /**
+     * Get extra height from plugins that appears before a given row index.
+     * Used by virtualization to correctly position the scroll window.
+     */
+    getExtraHeightBefore(beforeRowIndex: number): number;
+    /**
+     * Adjust the virtualization start index based on plugin needs.
+     * Returns the minimum start index from all plugins.
+     */
+    adjustVirtualStart(start: number, scrollTop: number, rowHeight: number): number;
     /**
      * Execute renderRow hook on all plugins.
      * Returns true if any plugin handled the row.