@toolbox-web/grid 0.6.0 → 1.0.0

package/lib/core/grid.d.ts

@@ -1,9 +1,10 @@
 import { CellMouseEvent } from './plugin';
 import { BaseGridPlugin, PluginQuery } from './plugin/base-plugin';
-import { ColumnConfig, ColumnConfigMap, ColumnInternal, FitMode, FrameworkAdapter, GridColumnState, GridConfig, HeaderContentDefinition, InternalGrid, ResizeController, ToolbarButtonConfig, ToolbarButtonInfo, ToolPanelDefinition, VirtualState } from './types';
+import { ColumnConfig, ColumnConfigMap, ColumnInternal, FitMode, FrameworkAdapter, GridColumnState, GridConfig, HeaderContentDefinition, InternalGrid, ResizeController, ToolbarContentDefinition, ToolPanelDefinition, UpdateSource, VirtualState } from './types';
 export declare class DataGridElement<T = any> extends HTMLElement implements InternalGrid<T> {
     #private;
     static readonly tagName = "tbw-grid";
+    /** Version of the grid component, injected at build time from package.json */
     static readonly version: string;
     /**
      * Registry of framework adapters that handle converting light DOM elements
@@ -23,29 +24,21 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * // One-time setup in app
      * GridElement.registerAdapter(new AngularGridAdapter(injector, appRef));
      * ```
+     * @category Framework Adapters
      */
     static registerAdapter(adapter: FrameworkAdapter): void;
     /**
      * Get all registered framework adapters.
      * Used internally by light DOM parsing to find adapters that can handle templates.
+     * @category Framework Adapters
      */
     static getAdapters(): readonly FrameworkAdapter[];
     /**
      * Clear all registered adapters (primarily for testing).
+     * @category Framework Adapters
      */
     static clearAdapters(): void;
     static get observedAttributes(): string[];
-    /**
-     * Access the grid's ShadowRoot.
-     *
-     * Note: The grid renders into its light DOM and does not attach a shadow root,
-     * so this getter returns `null`. Use `grid.querySelector()` directly for DOM queries.
-     *
-     * @deprecated This property returns `null` since Shadow DOM was removed.
-     *             Use `grid.querySelector()` or `grid.querySelectorAll()` directly.
-     * @returns null (no shadow root is attached)
-     */
-    get shadowRoot(): ShadowRoot | null;
     _rows: T[];
     get _columns(): ColumnInternal<T>[];
     set _columns(value: ColumnInternal<T>[]);
@@ -80,25 +73,134 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      */
     __frameworkAdapter?: FrameworkAdapter;
     __rowsBodyEl: HTMLElement | null;
+    /**
+     * Get or set the row data displayed in the grid.
+     *
+     * The getter returns processed rows (after filtering, sorting, grouping by plugins).
+     * The setter accepts new source data and triggers a re-render.
+     *
+     * @group Configuration
+     * @example
+     * ```typescript
+     * // Set initial data
+     * grid.rows = employees;
+     *
+     * // Update with new data (triggers re-render)
+     * grid.rows = [...employees, newEmployee];
+     *
+     * // Read current (processed) rows
+     * console.log(`Displaying ${grid.rows.length} rows`);
+     * ```
+     */
     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 the original unfiltered/unprocessed source rows.
+     *
+     * Use this when you need access to all source data regardless of active
+     * filters, sorting, or grouping applied by plugins. The `rows` property
+     * returns processed data, while `sourceRows` returns the original input.
+     *
+     * @group Configuration
+     * @example
+     * ```typescript
+     * // Get total count including filtered-out rows
+     * console.log(`${grid.rows.length} of ${grid.sourceRows.length} rows visible`);
+     *
+     * // Export all data, not just visible
+     * exportToCSV(grid.sourceRows);
+     * ```
      */
     get sourceRows(): T[];
+    /**
+     * Get or set the column configurations.
+     *
+     * The getter returns processed columns (after plugin transformations).
+     * The setter accepts an array of column configs or a column config map.
+     *
+     * @group Configuration
+     * @example
+     * ```typescript
+     * // Set columns as array
+     * grid.columns = [
+     *   { field: 'name', header: 'Name', width: 200 },
+     *   { field: 'email', header: 'Email' },
+     *   { field: 'role', header: 'Role', width: 120 }
+     * ];
+     *
+     * // Set columns as map (keyed by field)
+     * grid.columns = {
+     *   name: { header: 'Name', width: 200 },
+     *   email: { header: 'Email' },
+     *   role: { header: 'Role', width: 120 }
+     * };
+     *
+     * // Read current columns
+     * grid.columns.forEach(col => {
+     *   console.log(`${col.field}: ${col.width ?? 'auto'}`);
+     * });
+     * ```
+     */
     get columns(): ColumnConfig<T>[];
     set columns(value: ColumnConfig<T>[] | ColumnConfigMap<T> | undefined);
+    /**
+     * Get or set the full grid configuration object.
+     *
+     * The getter returns the effective (merged) configuration.
+     * The setter accepts a new configuration and triggers a full re-render.
+     *
+     * @group Configuration
+     * @example
+     * ```typescript
+     * import { SelectionPlugin, SortingPlugin } from '@toolbox-web/grid/all';
+     *
+     * // Set full configuration
+     * grid.gridConfig = {
+     *   columns: [
+     *     { field: 'name', header: 'Name' },
+     *     { field: 'status', header: 'Status' }
+     *   ],
+     *   fitMode: 'stretch',
+     *   plugins: [
+     *     new SelectionPlugin({ mode: 'row' }),
+     *     new SortingPlugin()
+     *   ]
+     * };
+     *
+     * // Read current configuration
+     * console.log('Fit mode:', grid.gridConfig.fitMode);
+     * console.log('Columns:', grid.gridConfig.columns?.length);
+     * ```
+     */
     get gridConfig(): GridConfig<T>;
     set gridConfig(value: GridConfig<T> | undefined);
+    /**
+     * Get or set the column sizing mode.
+     *
+     * - `'stretch'` (default): Columns stretch to fill available width
+     * - `'fixed'`: Columns use explicit widths; horizontal scroll if needed
+     * - `'auto'`: Columns auto-size to content on initial render
+     *
+     * @group Configuration
+     * @example
+     * ```typescript
+     * // Use fixed widths with horizontal scroll
+     * grid.fitMode = 'fixed';
+     *
+     * // Stretch columns to fill container
+     * grid.fitMode = 'stretch';
+     *
+     * // Auto-size columns based on content
+     * grid.fitMode = 'auto';
+     * ```
+     */
     get fitMode(): FitMode;
     set fitMode(value: FitMode | undefined);
-    get editOn(): string | boolean | undefined;
-    set editOn(value: string | boolean | undefined);
     /**
      * Effective config accessor for internal modules and plugins.
      * Returns the merged config (single source of truth) before plugin processing.
      * Use this when you need the raw merged config (e.g., for column definitions including hidden).
+     * @group State Access
      * @internal Plugin API
      */
     get effectiveConfig(): GridConfig<T>;
@@ -106,21 +208,27 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * 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.
+     * @group State Access
      * @internal Plugin API
      * @example
      * element.addEventListener('click', handler, { signal: this.grid.disconnectSignal });
      */
     get disconnectSignal(): AbortSignal;
+    /**
+     * @internal Do not call directly. Use `createGrid()` or `document.createElement('tbw-grid')`.
+     */
     constructor();
     /**
      * Get a plugin instance by its class.
      * Used by plugins for inter-plugin communication.
+     * @group Plugin Communication
      * @internal Plugin API
      */
     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).
+     * @group Plugin Communication
      * @internal Plugin API
      */
     getPluginByName(name: string): BaseGridPlugin | undefined;
@@ -128,6 +236,7 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * 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.
+     * @group Rendering
      * @internal Plugin API
      */
     requestRender(): void;
@@ -135,33 +244,40 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * Request a full re-render and restore focus styling afterward.
      * Use this when a plugin action (like expand/collapse) triggers a render
      * but needs to maintain keyboard navigation focus.
+     * @group Rendering
      * @internal Plugin API
      */
     requestRenderWithFocus(): void;
     /**
      * Update the grid's column template CSS.
      * Called by resize controller during column resize operations.
-     * @internal
+     * @group Rendering
+     * @internal Plugin API
      */
     updateTemplate(): 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.
+     * @group Rendering
      * @internal Plugin API
      */
     requestAfterRender(): void;
+    /** @internal Web component lifecycle - not part of public API */
     connectedCallback(): void;
+    /** @internal Web component lifecycle - not part of public API */
     disconnectedCallback(): void;
     /**
      * Handle HTML attribute changes.
      * Only processes attribute values when SET (non-null).
      * Removing an attribute does NOT clear JS-set properties.
+     * @internal Web component lifecycle - not part of public API
      */
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     /**
      * Find the header row element in the shadow DOM.
      * Used by plugins that need to access header cells for styling or measurement.
+     * @group DOM Access
      * @internal Plugin API
      */
     findHeaderRow(): HTMLElement;
@@ -169,18 +285,28 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * Find a rendered row element by its data row index.
      * Returns null if the row is not currently rendered (virtualized out of view).
      * Used by plugins that need to access specific row elements for styling or measurement.
+     * @group DOM Access
      * @internal Plugin API
      * @param rowIndex - The data row index (not the DOM position)
      */
     findRenderedRowElement(rowIndex: number): HTMLElement | null;
     /**
-     * Dispatch a cell click event to the plugin system.
-     * Returns true if any plugin handled the event.
+     * Dispatch a cell click event to the plugin system, then emit a public event.
+     * Plugins get first chance to handle the event. After plugins process it,
+     * a `cell-click` CustomEvent is dispatched for external listeners.
+     *
+     * @returns `true` if any plugin handled (consumed) the event, or if consumer canceled
+     * @fires cell-activate - Unified activation event (cancelable) - fires FIRST
+     * @fires cell-click - Emitted after plugins process the click, with full cell context
      */
     _dispatchCellClick(event: MouseEvent, rowIndex: number, colIndex: number, cellEl: HTMLElement): boolean;
     /**
-     * Dispatch a row click event to the plugin system.
-     * Returns true if any plugin handled the event.
+     * Dispatch a row click event to the plugin system, then emit a public event.
+     * Plugins get first chance to handle the event. After plugins process it,
+     * a `row-click` CustomEvent is dispatched for external listeners.
+     *
+     * @returns `true` if any plugin handled (consumed) the event
+     * @fires row-click - Emitted after plugins process the click, with full row context
      */
     _dispatchRowClick(event: MouseEvent, rowIndex: number, row: any, rowEl: HTMLElement): boolean;
     /**
@@ -206,6 +332,7 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
     /**
      * Query all plugins with a generic query and collect responses.
      * This enables inter-plugin communication without the core knowing plugin-specific concepts.
+     * @group Plugin Communication
      * @internal Plugin API
      *
      * @example
@@ -217,34 +344,233 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
     /**
      * Dispatch cell mouse events for drag operations.
      * Returns true if any plugin started a drag.
+     * @group Event Dispatching
      * @internal Plugin API - called by event-delegation.ts
      */
     _dispatchCellMouseDown(event: CellMouseEvent): boolean;
     /**
      * Dispatch cell mouse move during drag.
+     * @group Event Dispatching
      * @internal Plugin API - called by event-delegation.ts
      */
     _dispatchCellMouseMove(event: CellMouseEvent): void;
     /**
      * Dispatch cell mouse up to end drag.
+     * @group Event Dispatching
      * @internal Plugin API - called by event-delegation.ts
      */
     _dispatchCellMouseUp(event: CellMouseEvent): void;
+    /**
+     * Wait for the grid to be ready.
+     * Resolves once the component has finished initial setup, including
+     * column inference, plugin initialization, and first render.
+     *
+     * @group Lifecycle
+     * @returns Promise that resolves when the grid is ready
+     *
+     * @example
+     * ```typescript
+     * const grid = document.querySelector('tbw-grid');
+     * await grid.ready();
+     * console.log('Grid is ready, rows:', grid.rows.length);
+     * ```
+     */
     ready(): Promise<void>;
+    /**
+     * Force a full layout/render cycle.
+     * Use this after programmatic changes that require re-measurement,
+     * such as container resize or dynamic style changes.
+     *
+     * @group Lifecycle
+     * @returns Promise that resolves when the render cycle completes
+     *
+     * @example
+     * ```typescript
+     * // After resizing the container
+     * container.style.width = '800px';
+     * await grid.forceLayout();
+     * console.log('Grid re-rendered');
+     * ```
+     */
     forceLayout(): Promise<void>;
     /**
-     * Trim the internal row pool to match the current visible window size.
+     * Get a frozen snapshot of the current effective configuration.
+     * The returned object is read-only and reflects all merged config sources.
      *
-     * The grid maintains a pool of reusable row DOM elements for virtualization.
-     * When the dataset shrinks significantly (e.g., after filtering or deleting rows),
-     * the pool may have excess elements that consume memory unnecessarily.
+     * @group Configuration
+     * @returns Promise resolving to frozen configuration object
      *
-    /** Public method: returns a frozen snapshot of the merged effective configuration */
+     * @example
+     * ```typescript
+     * const config = await grid.getConfig();
+     * console.log('Columns:', config.columns?.length);
+     * console.log('Fit mode:', config.fitMode);
+     * ```
+     */
     getConfig(): Promise<Readonly<GridConfig<T>>>;
+    /**
+     * Get the unique ID for a row.
+     * Uses the configured `getRowId` function or falls back to `row.id` / `row._id`.
+     *
+     * @group Data Management
+     * @param row - The row object
+     * @returns The row's unique identifier
+     * @throws Error if no ID can be determined
+     *
+     * @example
+     * ```typescript
+     * const id = grid.getRowId(row);
+     * console.log('Row ID:', id);
+     * ```
+     */
+    getRowId(row: T): string;
+    /**
+     * Get a row by its ID.
+     * O(1) lookup via internal Map.
+     *
+     * @group Data Management
+     * @param id - Row identifier (from getRowId)
+     * @returns The row object, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const row = grid.getRow('cargo-123');
+     * if (row) {
+     *   console.log('Found:', row.name);
+     * }
+     * ```
+     */
+    getRow(id: string): T | undefined;
+    /**
+     * Update a row by ID.
+     * Mutates the row in-place and emits `cell-change` for each changed field.
+     *
+     * @group Data Management
+     * @param id - Row identifier (from getRowId)
+     * @param changes - Partial row data to merge
+     * @param source - Origin of update (default: 'api')
+     * @throws Error if row is not found
+     * @fires cell-change - For each field that changed
+     *
+     * @example
+     * ```typescript
+     * // WebSocket update handler
+     * socket.on('cargo-update', (data) => {
+     *   grid.updateRow(data.id, { status: data.status, eta: data.eta });
+     * });
+     * ```
+     */
+    updateRow(id: string, changes: Partial<T>, source?: UpdateSource): void;
+    /**
+     * Batch update multiple rows.
+     * More efficient than multiple `updateRow()` calls - single render cycle.
+     *
+     * @group Data Management
+     * @param updates - Array of { id, changes } objects
+     * @param source - Origin of updates (default: 'api')
+     * @throws Error if any row is not found
+     * @fires cell-change - For each field that changed on each row
+     *
+     * @example
+     * ```typescript
+     * // Bulk status update
+     * grid.updateRows([
+     *   { id: 'cargo-1', changes: { status: 'shipped' } },
+     *   { id: 'cargo-2', changes: { status: 'shipped' } },
+     * ]);
+     * ```
+     */
+    updateRows(updates: Array<{
+        id: string;
+        changes: Partial<T>;
+    }>, source?: UpdateSource): void;
+    /**
+     * Show or hide a column by field name.
+     *
+     * @group Column Visibility
+     * @param field - The field name of the column to modify
+     * @param visible - Whether the column should be visible
+     * @returns `true` if the visibility changed, `false` if unchanged
+     * @fires column-state-change - Emitted when the visibility changes
+     *
+     * @example
+     * ```typescript
+     * // Hide the email column
+     * grid.setColumnVisible('email', false);
+     *
+     * // Show it again
+     * grid.setColumnVisible('email', true);
+     * ```
+     */
     setColumnVisible(field: string, visible: boolean): boolean;
+    /**
+     * Toggle a column's visibility.
+     *
+     * @group Column Visibility
+     * @param field - The field name of the column to toggle
+     * @returns The new visibility state (`true` = visible, `false` = hidden)
+     * @fires column-state-change - Emitted when the visibility changes
+     *
+     * @example
+     * ```typescript
+     * // Toggle the notes column visibility
+     * const isNowVisible = grid.toggleColumnVisibility('notes');
+     * console.log(`Notes column is now ${isNowVisible ? 'visible' : 'hidden'}`);
+     * ```
+     */
     toggleColumnVisibility(field: string): boolean;
+    /**
+     * Check if a column is currently visible.
+     *
+     * @group Column Visibility
+     * @param field - The field name to check
+     * @returns `true` if the column is visible, `false` if hidden
+     *
+     * @example
+     * ```typescript
+     * if (grid.isColumnVisible('email')) {
+     *   console.log('Email column is showing');
+     * }
+     * ```
+     */
     isColumnVisible(field: string): boolean;
+    /**
+     * Show all columns, resetting any hidden columns to visible.
+     *
+     * @group Column Visibility
+     * @fires column-state-change - Emitted when column visibility changes
+     * @example
+     * ```typescript
+     * // Reset button handler
+     * resetButton.onclick = () => grid.showAllColumns();
+     * ```
+     */
     showAllColumns(): void;
+    /**
+     * Get metadata for all columns including visibility state.
+     * Useful for building a column picker UI.
+     *
+     * @group Column Visibility
+     * @returns Array of column info objects
+     *
+     * @example
+     * ```typescript
+     * // Build a column visibility menu
+     * const columns = grid.getAllColumns();
+     * columns.forEach(col => {
+     *   if (!col.utility) { // Skip utility columns like selection checkbox
+     *     const menuItem = document.createElement('label');
+     *     menuItem.innerHTML = `
+     *       <input type="checkbox" ${col.visible ? 'checked' : ''}>
+     *       ${col.header}
+     *     `;
+     *     menuItem.querySelector('input').onchange = () =>
+     *       grid.toggleColumnVisibility(col.field);
+     *     menu.appendChild(menuItem);
+     *   }
+     * });
+     * ```
+     */
     getAllColumns(): Array<{
         field: string;
         header: string;
@@ -252,20 +578,80 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
         lockVisible?: boolean;
         utility?: boolean;
     }>;
+    /**
+     * Set the display order of columns.
+     *
+     * @group Column Order
+     * @param order - Array of field names in desired order
+     * @fires column-state-change - Emitted when column order changes
+     *
+     * @example
+     * ```typescript
+     * // Move 'status' column to first position
+     * const currentOrder = grid.getColumnOrder();
+     * const newOrder = ['status', ...currentOrder.filter(f => f !== 'status')];
+     * grid.setColumnOrder(newOrder);
+     * ```
+     */
     setColumnOrder(order: string[]): void;
+    /**
+     * Get the current column display order.
+     *
+     * @group Column Order
+     * @returns Array of field names in display order
+     *
+     * @example
+     * ```typescript
+     * const order = grid.getColumnOrder();
+     * console.log('Columns:', order.join(', '));
+     * ```
+     */
     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.
+     * Get the current column state for persistence.
+     * Returns a serializable object including column order, widths, visibility,
+     * sort state, and any plugin-specific state.
+     *
+     * Use this to save user preferences to localStorage or a database.
+     *
+     * @group State Persistence
+     * @returns Serializable column state object
+     *
+     * @example
+     * ```typescript
+     * // Save state to localStorage
+     * const state = grid.getColumnState();
+     * localStorage.setItem('gridState', JSON.stringify(state));
+     *
+     * // Later, restore the state
+     * const saved = localStorage.getItem('gridState');
+     * if (saved) {
+     *   grid.columnState = JSON.parse(saved);
+     * }
+     * ```
      */
     getColumnState(): GridColumnState;
     /**
-     * Set the column state, restoring order, width, visibility, sort, and plugin state.
-     * Use this to restore previously saved column state.
+     * Set the column state, restoring all saved preferences.
+     * Can be set before or after grid initialization.
+     *
+     * @group State Persistence
+     * @fires column-state-change - Emitted after state is applied (if grid is initialized)
+     * @example
+     * ```typescript
+     * // Restore saved state on page load
+     * const grid = document.querySelector('tbw-grid');
+     * const saved = localStorage.getItem('myGridState');
+     * if (saved) {
+     *   grid.columnState = JSON.parse(saved);
+     * }
+     * ```
      */
     set columnState(state: GridColumnState | undefined);
     /**
      * Get the current column state.
+     * Alias for `getColumnState()` for property-style access.
+     * @group State Persistence
      */
     get columnState(): GridColumnState | undefined;
     /**
@@ -273,54 +659,312 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * 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.
+     * @group State Persistence
      * @internal Plugin API
      */
     requestStateChange(): void;
     /**
      * Reset column state to initial configuration.
-     * Clears all user modifications (order, width, visibility, sort).
+     * Clears all user modifications including order, widths, visibility, and sort.
+     *
+     * @group State Persistence
+     * @fires column-state-change - Emitted after state is reset
+     * @example
+     * ```typescript
+     * // Reset button handler
+     * resetBtn.onclick = () => {
+     *   grid.resetColumnState();
+     *   localStorage.removeItem('gridState');
+     * };
+     * ```
      */
     resetColumnState(): void;
-    /** Check if the tool panel is currently open. */
+    /**
+     * Check if the tool panel sidebar is currently open.
+     *
+     * The tool panel is an accordion-based sidebar that contains sections
+     * registered by plugins or via `registerToolPanel()`.
+     *
+     * @group Tool Panel
+     * @example
+     * ```typescript
+     * // Conditionally show/hide a "toggle panel" button
+     * const isPanelOpen = grid.isToolPanelOpen;
+     * toggleButton.textContent = isPanelOpen ? 'Close Panel' : 'Open Panel';
+     * ```
+     */
     get isToolPanelOpen(): boolean;
     /**
-     * Get the currently active tool panel ID, or null if none is open.
-     * @deprecated Use isToolPanelOpen and expandedToolPanelSections instead.
+     * Get the IDs of currently expanded accordion sections in the tool panel.
+     *
+     * Multiple sections can be expanded simultaneously in the accordion view.
+     *
+     * @group Tool Panel
+     * @example
+     * ```typescript
+     * // Check which sections are expanded
+     * const expanded = grid.expandedToolPanelSections;
+     * console.log('Expanded sections:', expanded);
+     * // e.g., ['columnVisibility', 'filtering']
+     * ```
      */
-    get activeToolPanel(): string | null;
-    /** Get the IDs of expanded accordion sections. */
     get expandedToolPanelSections(): string[];
-    /** Open the tool panel (accordion view with all registered panels). */
+    /**
+     * Open the tool panel sidebar.
+     *
+     * The tool panel displays an accordion view with all registered panel sections.
+     * Each section can be expanded/collapsed independently.
+     *
+     * @group Tool Panel
+     * @example
+     * ```typescript
+     * // Open the tool panel when a toolbar button is clicked
+     * settingsButton.addEventListener('click', () => {
+     *   grid.openToolPanel();
+     * });
+     * ```
+     */
     openToolPanel(): void;
-    /** Close the tool panel. */
+    /**
+     * Close the tool panel sidebar.
+     *
+     * @group Tool Panel
+     * @example
+     * ```typescript
+     * // Close the panel after user makes a selection
+     * grid.closeToolPanel();
+     * ```
+     */
     closeToolPanel(): void;
-    /** Toggle the tool panel open/closed. */
+    /**
+     * Toggle the tool panel sidebar open or closed.
+     *
+     * @group Tool Panel
+     * @example
+     * ```typescript
+     * // Wire up a toggle button
+     * toggleButton.addEventListener('click', () => {
+     *   grid.toggleToolPanel();
+     * });
+     * ```
+     */
     toggleToolPanel(): void;
-    /** Toggle an accordion section expanded/collapsed. */
+    /**
+     * Toggle an accordion section expanded or collapsed within the tool panel.
+     *
+     * @group Tool Panel
+     * @param sectionId - The ID of the section to toggle (matches `ToolPanelDefinition.id`)
+     *
+     * @example
+     * ```typescript
+     * // Expand the column visibility section programmatically
+     * grid.openToolPanel();
+     * grid.toggleToolPanelSection('columnVisibility');
+     * ```
+     */
     toggleToolPanelSection(sectionId: string): void;
-    /** Get registered tool panel definitions. */
+    /**
+     * Get all registered tool panel definitions.
+     *
+     * Returns both plugin-registered panels and panels registered via `registerToolPanel()`.
+     *
+     * @group Tool Panel
+     * @returns Array of tool panel definitions
+     *
+     * @example
+     * ```typescript
+     * // List all available panels
+     * const panels = grid.getToolPanels();
+     * panels.forEach(panel => {
+     *   console.log(`Panel: ${panel.title} (${panel.id})`);
+     * });
+     * ```
+     */
     getToolPanels(): ToolPanelDefinition[];
-    /** Register a custom tool panel (without creating a plugin). */
+    /**
+     * Register a custom tool panel section.
+     *
+     * Use this API to add custom UI sections to the tool panel sidebar
+     * without creating a full plugin. The panel will appear as an accordion
+     * section in the tool panel.
+     *
+     * @group Tool Panel
+     * @param panel - The tool panel definition
+     *
+     * @example
+     * ```typescript
+     * // Register a custom "Export" panel
+     * grid.registerToolPanel({
+     *   id: 'export',
+     *   title: 'Export Options',
+     *   icon: '📥',
+     *   order: 50, // Lower order = higher in list
+     *   render: (container) => {
+     *     container.innerHTML = `
+     *       <button id="export-csv">Export CSV</button>
+     *       <button id="export-json">Export JSON</button>
+     *     `;
+     *     container.querySelector('#export-csv')?.addEventListener('click', () => {
+     *       exportToCSV(grid.rows);
+     *     });
+     *   }
+     * });
+     * ```
+     */
     registerToolPanel(panel: ToolPanelDefinition): void;
-    /** Unregister a custom tool panel. */
+    /**
+     * Unregister a custom tool panel section.
+     *
+     * @group Tool Panel
+     * @param panelId - The ID of the panel to remove
+     *
+     * @example
+     * ```typescript
+     * // Remove the export panel when no longer needed
+     * grid.unregisterToolPanel('export');
+     * ```
+     */
     unregisterToolPanel(panelId: string): void;
-    /** Get registered header content definitions. */
+    /**
+     * Get all registered header content definitions.
+     *
+     * @group Header Content
+     * @returns Array of header content definitions
+     *
+     * @example
+     * ```typescript
+     * const contents = grid.getHeaderContents();
+     * console.log('Header sections:', contents.map(c => c.id));
+     * ```
+     */
     getHeaderContents(): HeaderContentDefinition[];
-    /** Register custom header content (without creating a plugin). */
+    /**
+     * Register custom header content.
+     *
+     * Header content appears in the grid's header bar area, which is displayed
+     * above the column headers. Use this for search boxes, filters, or other
+     * controls that should be prominently visible.
+     *
+     * @group Header Content
+     * @param content - The header content definition
+     *
+     * @example
+     * ```typescript
+     * // Add a global search box to the header
+     * grid.registerHeaderContent({
+     *   id: 'global-search',
+     *   order: 10,
+     *   render: (container) => {
+     *     const input = document.createElement('input');
+     *     input.type = 'search';
+     *     input.placeholder = 'Search all columns...';
+     *     input.addEventListener('input', (e) => {
+     *       const term = (e.target as HTMLInputElement).value;
+     *       filterGrid(term);
+     *     });
+     *     container.appendChild(input);
+     *   }
+     * });
+     * ```
+     */
     registerHeaderContent(content: HeaderContentDefinition): void;
-    /** Unregister custom header content. */
+    /**
+     * Unregister custom header content.
+     *
+     * @group Header Content
+     * @param contentId - The ID of the content to remove
+     *
+     * @example
+     * ```typescript
+     * grid.unregisterHeaderContent('global-search');
+     * ```
+     */
     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;
+    /**
+     * Get all registered toolbar content definitions.
+     *
+     * @group Toolbar
+     * @returns Array of toolbar content definitions
+     *
+     * @example
+     * ```typescript
+     * const contents = grid.getToolbarContents();
+     * console.log('Toolbar items:', contents.map(c => c.id));
+     * ```
+     */
+    getToolbarContents(): ToolbarContentDefinition[];
+    /**
+     * Register custom toolbar content.
+     *
+     * Toolbar content appears in the grid's toolbar area. Use this for action
+     * buttons, dropdowns, or other controls that should be easily accessible.
+     * Content is rendered in order of the `order` property (lower = first).
+     *
+     * @group Toolbar
+     * @param content - The toolbar content definition
+     *
+     * @example
+     * ```typescript
+     * // Add export buttons to the toolbar
+     * grid.registerToolbarContent({
+     *   id: 'export-buttons',
+     *   order: 100, // Position in toolbar (lower = first)
+     *   render: (container) => {
+     *     const csvBtn = document.createElement('button');
+     *     csvBtn.textContent = 'Export CSV';
+     *     csvBtn.className = 'dg-toolbar-btn';
+     *     csvBtn.addEventListener('click', () => exportToCSV(grid.rows));
+     *
+     *     const jsonBtn = document.createElement('button');
+     *     jsonBtn.textContent = 'Export JSON';
+     *     jsonBtn.className = 'dg-toolbar-btn';
+     *     jsonBtn.addEventListener('click', () => exportToJSON(grid.rows));
+     *
+     *     container.append(csvBtn, jsonBtn);
+     *   }
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Add a dropdown filter to the toolbar
+     * grid.registerToolbarContent({
+     *   id: 'status-filter',
+     *   order: 50,
+     *   render: (container) => {
+     *     const select = document.createElement('select');
+     *     select.innerHTML = `
+     *       <option value="">All Statuses</option>
+     *       <option value="active">Active</option>
+     *       <option value="inactive">Inactive</option>
+     *     `;
+     *     select.addEventListener('change', (e) => {
+     *       const status = (e.target as HTMLSelectElement).value;
+     *       applyStatusFilter(status);
+     *     });
+     *     container.appendChild(select);
+     *   }
+     * });
+     * ```
+     */
+    registerToolbarContent(content: ToolbarContentDefinition): void;
+    /**
+     * Unregister custom toolbar content.
+     *
+     * @group Toolbar
+     * @param contentId - The ID of the content to remove
+     *
+     * @example
+     * ```typescript
+     * // Remove export buttons when switching to read-only mode
+     * grid.unregisterToolbarContent('export-buttons');
+     * ```
+     */
+    unregisterToolbarContent(contentId: string): void;
     /**
      * Re-parse light DOM shell elements and refresh shell header.
      * Call this after dynamically modifying <tbw-grid-header> children.
+     * @internal Plugin API
      */
     refreshShellHeader(): void;
     /**
@@ -329,6 +973,7 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      *
      * Uses adoptedStyleSheets for efficiency - styles survive shadow DOM rebuilds.
      *
+     * @group Custom Styles
      * @param id - Unique identifier for the style block (for removal/updates)
      * @param css - CSS string to inject
      *
@@ -350,18 +995,22 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
     registerStyles(id: string, css: string): void;
     /**
      * Remove previously registered custom styles.
+     *
+     * @group Custom Styles
      * @param id - The ID used when registering the styles
      */
     unregisterStyles(id: string): void;
     /**
      * Get list of registered custom style IDs.
+     *
+     * @group Custom Styles
      */
     getRegisteredStyles(): string[];
     /**
      * Re-parse light DOM column elements and refresh the grid.
      * Call this after framework adapters have registered their templates.
      * Uses the render scheduler to batch with other pending updates.
-     * @internal Used by framework integration libraries (Angular, React, Vue)
+     * @category Framework Adapters
      */
     refreshColumns(): void;
     /**