@toolbox-web/grid 1.24.1 → 1.25.0

package/lib/core/types.d.ts

@@ -1,3 +1,4 @@
+import { ShellState } from './internal/shell';
 import { RowPosition } from './internal/virtualization';
 import { PluginQuery } from './plugin/base-plugin';
 import { AfterCellRenderContext, AfterRowRenderContext, CellMouseEvent } from './plugin/types';
@@ -22,7 +23,7 @@ export type RowPositionEntry = RowPosition;
  * // Query existing grid
  * const grid = document.querySelector('tbw-grid') as DataGridElement<Employee>;
  * grid.rows = employees;
- * grid.addEventListener('cell-click', (e) => console.log(e.detail));
+ * grid.on('cell-click', (detail) => console.log(detail));
  *
  * // Create grid programmatically
  * import { createGrid } from '@toolbox-web/grid';
@@ -382,6 +383,13 @@ export interface PublicGrid<T = any> {
  * @category Plugin Development
  */
 export interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
+    /** The element's `id` attribute. Available because DataGridElement extends HTMLElement. */
+    id: string;
+    /**
+     * The grid's host HTMLElement (`this`). Use instead of casting `grid as unknown as HTMLElement`.
+     * @internal
+     */
+    readonly _hostElement: HTMLElement;
     querySelector<K extends keyof HTMLElementTagNameMap>(selectors: K): HTMLElementTagNameMap[K] | null;
     querySelector<E extends Element = Element>(selectors: string): E | null;
     querySelectorAll<K extends keyof HTMLElementTagNameMap>(selectors: K): NodeListOf<HTMLElementTagNameMap[K]>;
@@ -431,9 +439,13 @@ export interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     changedRows?: T[];
     /** Get IDs of all changed rows. Injected by EditingPlugin. */
     changedRowIds?: string[];
+    /** Internal Set for O(1) lookup in the render hot path. Injected by EditingPlugin. @internal */
+    _changedRowIdSet?: ReadonlySet<string>;
     effectiveConfig?: GridConfig<T>;
     findHeaderRow?: () => HTMLElement;
     refreshVirtualWindow: (full: boolean, skipAfterRender?: boolean) => boolean;
+    /** @internal Trigger a COLUMNS-phase re-render. */
+    refreshColumns?: () => void;
     updateTemplate?: () => void;
     findRenderedRowElement?: (rowIndex: number) => HTMLElement | null;
     /** Get a row by its ID. Implemented in grid.ts */
@@ -462,7 +474,7 @@ export interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     /** Dispatch row click to plugin system, returns true if handled */
     _dispatchRowClick?: (event: MouseEvent, rowIndex: number, row: any, rowEl: HTMLElement) => boolean;
     /** Dispatch header click to plugin system, returns true if handled */
-    _dispatchHeaderClick?: (event: MouseEvent, col: ColumnConfig, headerEl: HTMLElement) => boolean;
+    _dispatchHeaderClick?: (event: MouseEvent | KeyboardEvent, col: ColumnConfig, headerEl: HTMLElement) => boolean;
     /** Dispatch keydown to plugin system, returns true if handled */
     _dispatchKeyDown?: (event: KeyboardEvent) => boolean;
     /** Dispatch cell mouse events for drag operations. Returns true if any plugin started a drag. */
@@ -489,7 +501,48 @@ export interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     queryPlugins?: <T>(query: PluginQuery) => T[];
     /** Request emission of column-state-change event (debounced) */
     requestStateChange?: () => void;
+    /** @internal */ _renderVisibleRows(start: number, end: number, epoch?: number): void;
+    /** @internal */ _updateAriaCounts(totalRows: number, totalCols: number): void;
+    /** @internal */ _requestSchedulerPhase(phase: number, source: string): void;
+    /** @internal */ _rebuildRowIdMap(): void;
+    /** @internal */ _emitDataChange(): void;
+    /** @internal */ _getPluginExtraHeight(): number;
+    /** @internal */ _getPluginRowHeight(row: T, index: number): number | undefined;
+    /** @internal */ _getPluginExtraHeightBefore(start: number): number;
+    /** @internal */ _adjustPluginVirtualStart(start: number, scrollTop: number, rowHeight: number): number | undefined;
+    /** @internal */ _afterPluginRender(): void;
+    /** @internal */ _emitPluginEvent(event: string, detail: unknown): void;
+    /** @internal */ _schedulerMergeConfig(): void;
+    /** @internal */ _schedulerProcessColumns(): void;
+    /** @internal */ _schedulerProcessRows(): void;
+    /** @internal */ _schedulerRenderHeader(): void;
+    /** @internal */ _schedulerUpdateTemplate(): void;
+    /** @internal */ _schedulerAfterRender(): void;
+    /** @internal */ readonly _schedulerIsConnected: boolean;
+    /** @internal The render root element for DOM queries. */
+    readonly _renderRoot: Element;
+    /** @internal Emit a custom event from the grid. */
+    _emit(eventName: string, detail: unknown): void;
+    /** @internal Get accordion expand/collapse icons from effective config. */
+    readonly _accordionIcons: {
+        expand: IconValue;
+        collapse: IconValue;
+    };
+    /** @internal Shell state for config manager shell merging. */
+    readonly _shellState: ShellState;
+    /** @internal Clear the row pool and body element. */
+    _clearRowPool(): void;
+    /** @internal Run grid setup (DOM rebuild). */
+    _setup(): void;
+    /** @internal Apply animation configuration to host element. */
+    _applyAnimationConfig(config: GridConfig): void;
 }
+/**
+ * Grid reference type combining InternalGrid with HTMLElement.
+ * Used by extracted managers that need both internal grid state and DOM APIs.
+ * @internal
+ */
+export type GridHost<T = any> = InternalGrid<T> & HTMLElement;
 /**
  * Built-in primitive column types with automatic formatting and editing support.
  *
@@ -839,9 +892,12 @@ export interface ColumnConfig<TRow = any> extends BaseColumnConfig<TRow, any> {
      *
      * // Status-based styling
      * cellClass: (value) => [`status-${value}`]
+     *
+     * // Single class as string
+     * cellClass: (value) => value < 0 ? 'negative' : ''
      * ```
      */
-    cellClass?: (value: unknown, row: TRow, column: ColumnConfig<TRow>) => string[];
+    cellClass?: (value: unknown, row: TRow, column: ColumnConfig<TRow>) => string | string[];
     /**
      * Custom header label renderer. Customize the label content while the grid
      * handles sort icons, filter buttons, resize handles, and click interactions.
@@ -1032,9 +1088,9 @@ export interface ColumnEditorContext<TRow = any, TValue = any> {
      * @example
      * ```typescript
      * // In a cell-commit listener:
-     * grid.addEventListener('cell-commit', (e) => {
-     *   if (e.detail.field === 'quantity') {
-     *     e.detail.updateRow({ total: e.detail.row.price * e.detail.value });
+     * grid.on('cell-commit', (detail) => {
+     *   if (detail.field === 'quantity') {
+     *     detail.updateRow({ total: detail.row.price * detail.value });
      *   }
      * });
      * ```
@@ -1323,8 +1379,10 @@ export interface FrameworkAdapter {
     /**
      * Creates a view renderer function from a light DOM element.
      * The renderer receives cell context and returns DOM or string.
+     * Returns undefined if no renderer template is registered, allowing the grid
+     * to use its default rendering.
      */
-    createRenderer<TRow = unknown, TValue = unknown>(element: HTMLElement): ColumnViewRenderer<TRow, TValue>;
+    createRenderer<TRow = unknown, TValue = unknown>(element: HTMLElement): ColumnViewRenderer<TRow, TValue> | undefined;
     /**
      * Creates an editor spec from a light DOM element.
      * The editor receives context with commit/cancel and returns DOM.
@@ -1345,6 +1403,20 @@ export interface FrameworkAdapter {
      * @returns Type defaults for renderer/editor, or undefined if not registered
      */
     getTypeDefault?<TRow = unknown>(type: string): TypeDefault<TRow> | undefined;
+    /**
+     * Pre-process a grid config before the grid core applies it.
+     * Framework adapters use this to convert framework-specific component references
+     * (Angular classes, Vue components, React elements) to DOM-returning functions.
+     *
+     * Called automatically by the grid's `set gridConfig` setter when a
+     * `__frameworkAdapter` is present on the grid instance.
+     *
+     * Must be **idempotent** — already-processed configs must pass through safely.
+     *
+     * @param config - The raw grid config (may contain framework-specific values)
+     * @returns Processed config with DOM-returning functions
+     */
+    processConfig?<TRow = unknown>(config: GridConfig<TRow>): GridConfig<TRow>;
     /**
      * Called when a cell's content is about to be wiped (e.g., when exiting edit mode,
      * scroll-recycling a row, or rebuilding a row).
@@ -1366,6 +1438,16 @@ export interface FrameworkAdapter {
      * @param container - The container element returned by a create* method
      */
     unmount?(container: HTMLElement): void;
+    /**
+     * Parse a `<tbw-grid-detail>` element and return a detail renderer function.
+     * Used by MasterDetailPlugin to support framework-specific detail templates.
+     */
+    parseDetailElement?<TRow = unknown>(element: Element): ((row: TRow, rowIndex: number) => HTMLElement | string) | undefined;
+    /**
+     * Parse a `<tbw-grid-responsive-card>` element and return a card renderer function.
+     * Used by ResponsivePlugin to support framework-specific card templates.
+     */
+    parseResponsiveCardElement?<TRow = unknown>(element: Element): ((row: TRow, rowIndex: number) => HTMLElement) | undefined;
 }
 /**
  * Column internal properties used during light DOM parsing.
@@ -1890,9 +1972,12 @@ export interface GridConfig<TRow = any> {
      *
      * // Status-based row styling
      * rowClass: (row) => [`priority-${row.priority}`]
+     *
+     * // Single class as string
+     * rowClass: (row) => row.isNew ? 'new-row' : ''
      * ```
      */
-    rowClass?: (row: TRow) => string[];
+    rowClass?: (row: TRow) => string | string[];
     /** Sizing mode for columns. Can also be set via `fitMode` prop. */
     fitMode?: FitMode;
     /**
@@ -2328,6 +2413,31 @@ export interface LoadingContext {
  * @see {@link LoadingSize} for size variants ('large' | 'small')
  */
 export type LoadingRenderer = (context: LoadingContext) => HTMLElement | string;
+/**
+ * Detail for the `data-change` event.
+ *
+ * Fired whenever the grid's row data changes — including new data assignment,
+ * row insertion/removal, and in-place mutations via `updateRow()`.
+ *
+ * Use this to keep external UI in sync with the grid's current data state
+ * (row counts, summaries, charts, etc.).
+ *
+ * @example
+ * ```typescript
+ * grid.on('data-change', ({ rowCount, sourceRowCount }) => {
+ *   console.log(`${rowCount} rows visible of ${sourceRowCount} total`);
+ * });
+ * ```
+ *
+ * @see {@link DataGridEventMap} for all event types
+ * @category Events
+ */
+export interface DataChangeDetail {
+    /** Number of visible (processed) rows */
+    rowCount: number;
+    /** Total number of source rows (before filtering/grouping) */
+    sourceRowCount: number;
+}
 /**
  * Indicates the origin of a data change.
  * Used to prevent infinite loops in cascade update handlers.
@@ -2338,14 +2448,14 @@ export type LoadingRenderer = (context: LoadingContext) => HTMLElement | string;
  *
  * @example
  * ```typescript
- * grid.addEventListener('cell-change', (e) => {
- *   const { source, field, newValue } = e.detail;
+ * grid.on('cell-change', (detail) => {
+ *   const { source, field, newValue } = detail;
  *
  *   // Only cascade updates for user edits
  *   if (source === 'user' && field === 'price') {
  *     // Update calculated field (marked as 'cascade')
- *     grid.updateRow(e.detail.rowId, {
- *       total: newValue * e.detail.row.quantity,
+ *     grid.updateRow(detail.rowId, {
+ *       total: newValue * detail.row.quantity,
  *     });
  *   }
  *
@@ -2369,9 +2479,7 @@ export type UpdateSource = 'user' | 'cascade' | 'api';
  *
  * @example
  * ```typescript
- * grid.addEventListener('cell-change', (e: CustomEvent<CellChangeDetail>) => {
- *   const { row, rowId, field, oldValue, newValue, source } = e.detail;
- *
+ * grid.on('cell-change', ({ row, rowId, field, oldValue, newValue, source }) => {
  *   console.log(`${field} changed from ${oldValue} to ${newValue}`);
  *   console.log(`Change source: ${source}`);
  *
@@ -2811,11 +2919,12 @@ export interface ToolPanelDefinition {
  *     container.appendChild(span);
  *
  *     // Update on data changes
- *     const update = () => span.textContent = `${grid.rows.length} rows`;
- *     grid.addEventListener('data-change', update);
+ *     const unsub = grid.on('data-change', () => {
+ *       span.textContent = `${grid.rows.length} rows`;
+ *     });
  *
  *     return () => {
- *       grid.removeEventListener('data-change', update);
+ *       unsub();
  *     };
  *   },
  * });
@@ -2927,9 +3036,9 @@ export interface GridColumnState {
  *
  * @example
  * ```typescript
- * grid.addEventListener('cell-click', (e: CustomEvent<CellClickDetail>) => {
- *   const { row, field, value, rowIndex, colIndex } = e.detail;
- *   console.log(`Clicked ${field} = ${value} in row ${rowIndex}`);\n *
+ * grid.on('cell-click', ({ row, field, value, rowIndex, colIndex }) => {
+ *   console.log(`Clicked ${field} = ${value} in row ${rowIndex}`);
+ *
  *   // Access the full row data
  *   if (row.status === 'pending') {
  *     showApprovalDialog(row);
@@ -2963,8 +3072,7 @@ export interface CellClickDetail<TRow = unknown> {
  *
  * @example
  * ```typescript
- * grid.addEventListener('row-click', (e: CustomEvent<RowClickDetail>) => {
- *   const { row, rowIndex, rowEl } = e.detail;
+ * grid.on('row-click', ({ row, rowIndex, rowEl }) => {
  *   console.log(`Clicked row ${rowIndex}: ${row.name}`);
  *
  *   // Highlight the row
@@ -2992,9 +3100,7 @@ export interface RowClickDetail<TRow = unknown> {
  *
  * @example
  * ```typescript
- * grid.addEventListener('sort-change', (e: CustomEvent<SortChangeDetail>) => {
- *   const { field, direction } = e.detail;
- *
+ * grid.on('sort-change', ({ field, direction }) => {
  *   if (direction === 0) {
  *     console.log(`Sort cleared on ${field}`);
  *   } else {
@@ -3022,8 +3128,7 @@ export interface SortChangeDetail {
  *
  * @example
  * ```typescript
- * grid.addEventListener('column-resize', (e: CustomEvent<ColumnResizeDetail>) => {
- *   const { field, width } = e.detail;
+ * grid.on('column-resize', ({ field, width }) => {
  *   console.log(`Column ${field} resized to ${width}px`);
  *
  *   // Persist to user preferences
@@ -3056,9 +3161,7 @@ export type CellActivateTrigger = 'keyboard' | 'pointer';
  *
  * @example
  * ```typescript
- * grid.addEventListener('cell-activate', (e: CustomEvent<CellActivateDetail>) => {
- *   const { row, field, value, trigger, cellEl } = e.detail;
- *
+ * grid.on('cell-activate', ({ row, field, value, trigger, cellEl }, event) => {
  *   if (trigger === 'keyboard') {
  *     console.log('Activated via Enter key');
  *   } else {
@@ -3067,8 +3170,8 @@ export type CellActivateTrigger = 'keyboard' | 'pointer';
  *
  *   // Start custom editing for specific columns
  *   if (field === 'notes') {
+ *     event.preventDefault(); // Prevent default editing
  *     openNotesEditor(row, cellEl);
- *     e.preventDefault(); // Prevent default editing
  *   }
  * });
  * ```
@@ -3097,7 +3200,7 @@ export interface CellActivateDetail<TRow = unknown> {
 }
 /**
  * @deprecated Use `CellActivateDetail` instead. Will be removed in next major version.
- * Kept for backwards compatibility.
+ * Kept for backwards compatibility. Will be removed in v2.
  *
  * @category Events
  */
@@ -3116,8 +3219,7 @@ export interface ActivateCellDetail {
  * @example
  * ```typescript
  * // Framework adapter listens for this event
- * grid.addEventListener('mount-external-view', (e: CustomEvent<ExternalMountViewDetail>) => {
- *   const { placeholder, spec, context } = e.detail;
+ * grid.on('mount-external-view', ({ placeholder, spec, context }) => {
  *   // Mount framework component into placeholder
  *   mountComponent(spec.component, placeholder, context);
  * });
@@ -3146,8 +3248,7 @@ export interface ExternalMountViewDetail<TRow = unknown> {
  * @example
  * ```typescript
  * // Framework adapter listens for this event
- * grid.addEventListener('mount-external-editor', (e: CustomEvent<ExternalMountEditorDetail>) => {
- *   const { placeholder, spec, context } = e.detail;
+ * grid.on('mount-external-editor', ({ placeholder, spec, context }) => {
  *   // Mount framework editor with commit/cancel wired
  *   mountEditor(spec.component, placeholder, {
  *     value: context.value,
@@ -3176,39 +3277,242 @@ export interface ExternalMountEditorDetail<TRow = unknown> {
 /**
  * Maps event names to their detail payload types.
  *
- * Use this interface for strongly typed event handling.
+ * Used by {@link DataGridElement.on | grid.on()} and `addEventListener()` for
+ * fully typed event handling. Plugins extend this map via module augmentation.
  *
  * @example
  * ```typescript
- * // Type-safe event listener
- * function handleEvent<K extends keyof DataGridEventMap>(
- *   grid: DataGridElement,
- *   event: K,
- *   handler: (detail: DataGridEventMap[K]) => void,
- * ): void {
- *   grid.addEventListener(event, (e: CustomEvent) => handler(e.detail));
- * }
- *
- * handleEvent(grid, 'cell-click', (detail) => {
- *   console.log(detail.field); // Type-safe access
+ * // Recommended: grid.on() auto-unwraps the detail
+ * const off = grid.on('cell-click', ({ field, value, row }) => {
+ *   console.log(`Clicked ${field} = ${value}`);
  * });
+ * off(); // unsubscribe
+ *
+ * // addEventListener works too (useful for { once, signal, capture })
+ * grid.addEventListener('cell-click', (e) => {
+ *   console.log(e.detail.field);
+ * }, { once: true });
  * ```
  *
+ * @see {@link DataGridElement.on} for the recommended subscription API
  * @see {@link DataGridCustomEvent} for typed CustomEvent wrapper
  * @see {@link DGEvents} for event name constants
  * @category Events
  */
 export interface DataGridEventMap<TRow = unknown> {
+    /**
+     * Fired when a cell is clicked.
+     * Provides full context: row data, column config, cell element, and the original mouse event.
+     *
+     * @example
+     * ```typescript
+     * grid.on('cell-click', ({ row, field, value, cellEl }) => {
+     *   console.log(`Clicked ${field} = ${value}`);
+     *
+     *   // Open a detail dialog for a specific column
+     *   if (field === 'avatar') {
+     *     showImagePreview(row.avatarUrl, cellEl);
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link CellClickDetail}
+     * @group Core Events
+     */
     'cell-click': CellClickDetail<TRow>;
+    /**
+     * Fired when a row is clicked (anywhere on the row).
+     * Use for row-level actions like opening a detail panel or navigating.
+     *
+     * @example
+     * ```typescript
+     * grid.on('row-click', ({ row, rowIndex }) => {
+     *   console.log(`Row ${rowIndex}: ${row.name}`);
+     *
+     *   // Navigate to detail page
+     *   router.navigate(`/employees/${row.id}`);
+     * });
+     * ```
+     *
+     * @see {@link RowClickDetail}
+     * @group Core Events
+     */
     'row-click': RowClickDetail<TRow>;
+    /**
+     * Fired when a cell is activated by Enter key or pointer click.
+     * Unified event for both keyboard and pointer activation — use this
+     * instead of the deprecated `activate-cell`.
+     *
+     * Call `event.preventDefault()` to suppress default behavior (e.g., inline editing).
+     *
+     * @example
+     * ```typescript
+     * grid.on('cell-activate', ({ row, field, trigger, cellEl }, event) => {
+     *   // Custom editing for a specific column
+     *   if (field === 'notes') {
+     *     event.preventDefault();
+     *     openRichTextEditor(row, cellEl);
+     *   }
+     *
+     *   console.log(`Activated via ${trigger}`); // 'keyboard' | 'pointer'
+     * });
+     * ```
+     *
+     * @see {@link CellActivateDetail}
+     * @see {@link CellActivateTrigger}
+     * @group Core Events
+     */
     'cell-activate': CellActivateDetail<TRow>;
+    /**
+     * Fired after any data mutation — user edits, cascade updates, or API calls.
+     * This is an informational event for logging, auditing, or cascading updates
+     * to related fields. Check `source` to distinguish edit origins.
+     *
+     * @example
+     * ```typescript
+     * grid.on('cell-change', ({ row, rowId, field, oldValue, newValue, source }) => {
+     *   console.log(`${field}: ${oldValue} → ${newValue} (${source})`);
+     *
+     *   // Cascade: recalculate total when quantity changes
+     *   if (source === 'user' && field === 'quantity') {
+     *     grid.updateRow(rowId, { total: newValue * row.price });
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link CellChangeDetail}
+     * @see {@link UpdateSource}
+     * @group Core Events
+     */
     'cell-change': CellChangeDetail<TRow>;
+    /**
+     * Fired whenever the grid's row data changes — new data assignment,
+     * row insertion/removal, or in-place mutations via `updateRow()`.
+     * Use to keep external UI (row counts, summaries, charts) in sync.
+     *
+     * @example
+     * ```typescript
+     * grid.on('data-change', ({ rowCount, sourceRowCount }) => {
+     *   statusBar.textContent = `${rowCount} of ${sourceRowCount} rows`;
+     * });
+     * ```
+     *
+     * @see {@link DataChangeDetail}
+     * @group Core Events
+     */
+    'data-change': DataChangeDetail;
+    /**
+     * Emitted when a cell with an external view renderer (React, Angular, Vue component)
+     * needs to be mounted. Framework adapters listen for this event internally.
+     *
+     * @example
+     * ```typescript
+     * // Custom framework adapter
+     * grid.on('mount-external-view', ({ placeholder, spec, context }) => {
+     *   myFramework.render(spec.component, placeholder, {
+     *     row: context.row,
+     *     value: context.value,
+     *   });
+     * });
+     * ```
+     *
+     * @see {@link ExternalMountViewDetail}
+     * @see {@link FrameworkAdapter}
+     * @group Framework Adapter Events
+     */
     'mount-external-view': ExternalMountViewDetail<TRow>;
+    /**
+     * Emitted when a cell with an external editor component (React, Angular, Vue)
+     * needs to be mounted with commit/cancel bindings. Framework adapters listen
+     * for this event internally.
+     *
+     * @example
+     * ```typescript
+     * // Custom framework adapter
+     * grid.on('mount-external-editor', ({ placeholder, spec, context }) => {
+     *   myFramework.render(spec.component, placeholder, {
+     *     value: context.value,
+     *     onSave: context.commit,
+     *     onCancel: context.cancel,
+     *   });
+     * });
+     * ```
+     *
+     * @see {@link ExternalMountEditorDetail}
+     * @see {@link FrameworkAdapter}
+     * @group Framework Adapter Events
+     */
     'mount-external-editor': ExternalMountEditorDetail<TRow>;
+    /**
+     * Fired when the sort state changes — column header click, programmatic sort,
+     * or sort cleared. `direction: 0` indicates the sort was removed.
+     *
+     * @example
+     * ```typescript
+     * grid.on('sort-change', ({ field, direction }) => {
+     *   if (direction === 0) {
+     *     console.log('Sort cleared');
+     *   } else {
+     *     console.log(`Sorted by ${field} ${direction === 1 ? 'ASC' : 'DESC'}`);
+     *   }
+     *
+     *   // Server-side sorting
+     *   fetchData({ sortBy: field, sortDir: direction });
+     * });
+     * ```
+     *
+     * @see {@link SortChangeDetail}
+     * @see {@link SortHandler}
+     * @group Core Events
+     */
     'sort-change': SortChangeDetail;
+    /**
+     * Fired when a column is resized by the user dragging the resize handle.
+     * Use to persist column widths to user preferences or localStorage.
+     *
+     * @example
+     * ```typescript
+     * grid.on('column-resize', ({ field, width }) => {
+     *   console.log(`Column "${field}" resized to ${width}px`);
+     *
+     *   // Persist to localStorage
+     *   const widths = JSON.parse(localStorage.getItem('col-widths') ?? '{}');
+     *   widths[field] = width;
+     *   localStorage.setItem('col-widths', JSON.stringify(widths));
+     * });
+     * ```
+     *
+     * @see {@link ColumnResizeDetail}
+     * @group Core Events
+     */
     'column-resize': ColumnResizeDetail;
-    /** @deprecated Use 'cell-activate' instead */
+    /**
+     * @deprecated Use `cell-activate` instead. Will be removed in v2.
+     * @see {@link ActivateCellDetail}
+     * @group Core Events
+     */
     'activate-cell': ActivateCellDetail;
+    /**
+     * Fired when column state changes — reordering, resizing, visibility toggle,
+     * or sort changes. Use with `getColumnState()` / `columnState` setter for
+     * full state persistence.
+     *
+     * @example
+     * ```typescript
+     * grid.on('column-state-change', (state) => {
+     *   localStorage.setItem('grid-state', JSON.stringify(state));
+     *   console.log(`${state.columns.length} columns in state`);
+     * });
+     *
+     * // Restore on load
+     * const saved = localStorage.getItem('grid-state');
+     * if (saved) grid.columnState = JSON.parse(saved);
+     * ```
+     *
+     * @see {@link GridColumnState}
+     * @see {@link ColumnState}
+     * @group Core Events
+     */
     'column-state-change': GridColumnState;
 }
 /**
@@ -3238,19 +3542,26 @@ export type DataGridEventDetail<K extends keyof DataGridEventMap<unknown>, TRow
 /**
  * Custom event type for DataGrid events with typed detail payload.
  *
- * Use this type when you need to cast or declare event handler parameters.
+ * Primarily useful when you need to declare handler parameters with
+ * `addEventListener`. For most use cases, prefer {@link DataGridElement.on | grid.on()}
+ * which handles typing automatically.
  *
  * @example
  * ```typescript
- * // Strongly typed event handler
+ * // Typed handler for addEventListener
  * function onCellClick(e: DataGridCustomEvent<'cell-click', Employee>): void {
  *   const { row, field, value } = e.detail;
  *   console.log(`Clicked ${field} = ${value} on ${row.name}`);
  * }
- *
  * grid.addEventListener('cell-click', onCellClick);
+ *
+ * // With grid.on() you don't need this type — it's inferred:
+ * grid.on('cell-click', ({ row, field, value }) => {
+ *   console.log(`Clicked ${field} = ${value} on ${row.name}`);
+ * });
  * ```
  *
+ * @see {@link DataGridElement.on} for the recommended subscription API
  * @see {@link DataGridEventMap} for all event types
  * @see {@link DataGridEventDetail} for extracting detail type only
  * @category Events
@@ -3265,4 +3576,3 @@ export interface EvalContext {
     value: unknown;
     row: Record<string, unknown> | null;
 }
-//# sourceMappingURL=types.d.ts.map

package/lib/features/clipboard.d.ts

@@ -5,4 +5,3 @@ declare module '../core/types' {
         clipboard?: boolean | ClipboardConfig;
     }
 }
-//# sourceMappingURL=clipboard.d.ts.map

package/lib/features/column-virtualization.d.ts

@@ -5,4 +5,3 @@ declare module '../core/types' {
         columnVirtualization?: boolean | ColumnVirtualizationConfig;
     }
 }
-//# sourceMappingURL=column-virtualization.d.ts.map

package/lib/features/context-menu.d.ts

@@ -5,4 +5,3 @@ declare module '../core/types' {
         contextMenu?: boolean | ContextMenuConfig;
     }
 }
-//# sourceMappingURL=context-menu.d.ts.map

package/lib/features/editing.d.ts

@@ -5,4 +5,3 @@ declare module '../core/types' {
         editing?: boolean | 'click' | 'dblclick' | 'manual' | EditingConfig;
     }
 }
-//# sourceMappingURL=editing.d.ts.map

package/lib/features/export.d.ts

@@ -5,4 +5,3 @@ declare module '../core/types' {
         export?: boolean | ExportConfig;
     }
 }
-//# sourceMappingURL=export.d.ts.map

package/lib/features/filtering.d.ts

@@ -5,4 +5,3 @@ declare module '../core/types' {
         filtering?: boolean | FilterConfig<TRow>;
     }
 }
-//# sourceMappingURL=filtering.d.ts.map