@toolbox-web/grid 0.6.0 → 1.1.0

package/lib/core/types.d.ts

@@ -65,6 +65,8 @@ export interface PublicGrid<T = any> {
  * Member prefixes indicate accessibility:
  * - `_underscore` = protected members - private outside core, accessible to plugins. Marked with @internal.
  * - `__doubleUnderscore` = deeply internal members - private outside core, only for internal functions.
+ *
+ * @category Plugin Development
  */
 export interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     querySelector<K extends keyof HTMLElementTagNameMap>(selectors: K): HTMLElementTagNameMap[K] | null;
@@ -110,17 +112,21 @@ export interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     _activeEditRows?: number;
     /** Snapshots of row data before editing. Injected by EditingPlugin. @internal */
     _rowEditSnapshots?: Map<number, T>;
-    /** Set of row indices that have been modified. Injected by EditingPlugin. @internal */
-    _changedRowIndices?: Set<number>;
     /** Get all changed rows. Injected by EditingPlugin. */
     changedRows?: T[];
-    /** Get indices of all changed rows. Injected by EditingPlugin. */
-    changedRowIndices?: number[];
+    /** Get IDs of all changed rows. Injected by EditingPlugin. */
+    changedRowIds?: string[];
     effectiveConfig?: GridConfig<T>;
     findHeaderRow?: () => HTMLElement;
     refreshVirtualWindow: (full: boolean) => void;
     updateTemplate?: () => void;
     findRenderedRowElement?: (rowIndex: number) => HTMLElement | null;
+    /** Get a row by its ID. Implemented in grid.ts */
+    getRow?: (id: string) => T | undefined;
+    /** Get the unique ID for a row. Implemented in grid.ts */
+    getRowId?: (row: T) => string;
+    /** Update a row by ID. Implemented in grid.ts */
+    updateRow?: (id: string, changes: Partial<T>, source?: UpdateSource) => void;
     /** Begin bulk edit on a row. Injected by EditingPlugin. */
     beginBulkEdit?: (rowIndex: number) => void;
     /** Commit active row edit. Injected by EditingPlugin. */
@@ -150,7 +156,40 @@ export interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     /** Request emission of column-state-change event (debounced) */
     requestStateChange?: () => void;
 }
-export type PrimitiveColumnType = 'number' | 'string' | 'date' | 'boolean' | 'select' | 'typeahead';
+export type PrimitiveColumnType = 'number' | 'string' | 'date' | 'boolean' | 'select';
+/**
+ * Column type - built-in primitives or custom type strings.
+ * Custom types (e.g., 'currency', 'country') can have type-level defaults via `typeDefaults`.
+ */
+export type ColumnType = PrimitiveColumnType | (string & {});
+/**
+ * Type-level defaults for renderers and editors.
+ * Applied to all columns of a given type unless overridden at column level.
+ *
+ * @example
+ * ```typescript
+ * typeDefaults: {
+ *   country: {
+ *     renderer: (ctx) => {
+ *       const span = document.createElement('span');
+ *       span.innerHTML = `<img src="/flags/${ctx.value}.svg" /> ${ctx.value}`;
+ *       return span;
+ *     }
+ *   },
+ *   date: {
+ *     editor: (ctx) => createDatePickerEditor(ctx)
+ *   }
+ * }
+ * ```
+ */
+export interface TypeDefault<TRow = unknown> {
+    /** Renderer template for this type */
+    renderer?: ColumnViewRenderer<TRow, unknown>;
+    /** Editor template for this type (requires EditingPlugin) */
+    editor?: ColumnEditorSpec<TRow, unknown>;
+    /** Default editorParams for this type */
+    editorParams?: Record<string, unknown>;
+}
 /**
  * Base contract for a column. Public; kept intentionally lean so host apps can extend via intersection types.
  * Prefer adding optional properties here only when broadly useful to most grids.
@@ -160,8 +199,17 @@ export interface BaseColumnConfig<TRow = any, TValue = any> {
     field: keyof TRow & string;
     /** Visible header label; defaults to capitalized field */
     header?: string;
-    /** Column data type; inferred if omitted */
-    type?: PrimitiveColumnType;
+    /**
+     * Column data type.
+     *
+     * Built-in types: `'string'`, `'number'`, `'date'`, `'boolean'`, `'select'`
+     *
+     * Custom types (e.g., `'currency'`, `'country'`) can have type-level defaults
+     * via `gridConfig.typeDefaults` or framework adapter registries.
+     *
+     * @default Inferred from first row data
+     */
+    type?: ColumnType;
     /** Column width in pixels; fixed size (no flexibility) */
     width?: string | number;
     /** Minimum column width in pixels (stretch mode only); when set, column uses minmax(minWidth, 1fr) */
@@ -172,7 +220,7 @@ export interface BaseColumnConfig<TRow = any, TValue = any> {
     resizable?: boolean;
     /** Optional custom comparator for sorting (a,b) -> number */
     sortComparator?: (a: TValue, b: TValue, rowA: TRow, rowB: TRow) => number;
-    /** For select/typeahead types - available options */
+    /** For select type - available options */
     options?: Array<{
         label: string;
         value: unknown;
@@ -180,7 +228,7 @@ export interface BaseColumnConfig<TRow = any, TValue = any> {
         label: string;
         value: unknown;
     }>);
-    /** For select/typeahead - allow multi select */
+    /** For select - allow multi select */
     multi?: boolean;
     /** Optional formatter */
     format?: (value: TValue, row: TRow) => string;
@@ -329,6 +377,7 @@ export type ColumnViewRenderer<TRow = unknown, TValue = unknown> = (ctx: CellRen
  * // User registers adapter once in their app
  * GridElement.registerAdapter(new AngularGridAdapter(injector, appRef));
  * ```
+ * @category Framework Adapters
  */
 export interface FrameworkAdapter {
     /**
@@ -351,6 +400,14 @@ export interface FrameworkAdapter {
      * The renderer receives a container element and optionally returns a cleanup function.
      */
     createToolPanelRenderer?(element: HTMLElement): ((container: HTMLElement) => void | (() => void)) | undefined;
+    /**
+     * Gets type-level defaults from an application-level registry.
+     * Used by Angular's `GridTypeRegistry` and React's `GridTypeProvider`.
+     *
+     * @param type - The column type (e.g., 'date', 'currency', 'country')
+     * @returns Type defaults for renderer/editor, or undefined if not registered
+     */
+    getTypeDefault?<TRow = unknown>(type: string): TypeDefault<TRow> | undefined;
 }
 /**
  * Column internal properties used during light DOM parsing.
@@ -366,6 +423,8 @@ export interface ColumnParsedAttributes {
 /**
  * Extended column config used internally.
  * Includes all internal properties needed during grid lifecycle.
+ *
+ * @category Plugin Development
  * @internal
  */
 export interface ColumnInternal<T = any> extends ColumnConfig<T>, ColumnParsedAttributes {
@@ -383,6 +442,8 @@ export interface ColumnInternal<T = any> extends ColumnConfig<T>, ColumnParsedAt
 /**
  * Row element with internal tracking properties.
  * Used during virtualization and row pooling.
+ *
+ * @category Plugin Development
  * @internal
  */
 export interface RowElementInternal extends HTMLElement {
@@ -406,6 +467,8 @@ export interface ElementWithPart {
 /**
  * Compiled view function type with optional blocked flag.
  * The __blocked flag is set when a template contains unsafe expressions.
+ *
+ * @category Plugin Development
  * @internal
  */
 export interface CompiledViewFunction<T = any> {
@@ -415,6 +478,8 @@ export interface CompiledViewFunction<T = any> {
 }
 /**
  * Runtime cell context used internally for compiled template execution.
+ *
+ * @category Plugin Development
  */
 export interface CellContext<T = any> {
     row: T;
@@ -424,12 +489,18 @@ export interface CellContext<T = any> {
 }
 /**
  * Internal editor execution context extending the generic cell context with commit helpers.
+ *
+ * @category Plugin Development
  */
 export interface EditorExecContext<T = any> extends CellContext<T> {
     commit: (newValue: unknown) => void;
     cancel: () => void;
 }
-/** Controller managing drag-based column resize lifecycle. */
+/**
+ * Controller managing drag-based column resize lifecycle.
+ *
+ * @category Plugin Development
+ */
 export interface ResizeController {
     start: (e: MouseEvent, colIndex: number, cell: HTMLElement) => void;
     /** Reset a column to its configured width (or auto-size if none configured). */
@@ -438,7 +509,11 @@ export interface ResizeController {
     /** True while a resize drag is in progress (used to suppress header click/sort). */
     isResizing: boolean;
 }
-/** Virtual window bookkeeping; modified in-place as scroll position changes. */
+/**
+ * Virtual window bookkeeping; modified in-place as scroll position changes.
+ *
+ * @category Plugin Development
+ */
 export interface VirtualState {
     enabled: boolean;
     rowHeight: number;
@@ -456,6 +531,8 @@ export interface VirtualState {
 /**
  * Union type for input-like elements that have a `value` property.
  * Covers standard form elements and custom elements with value semantics.
+ *
+ * @category Plugin Development
  * @internal
  */
 export type InputLikeElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | {
@@ -479,7 +556,7 @@ export type AggregatorRef = string | ((rows: unknown[], field: string, column?:
 /** Result of automatic column inference from sample rows. */
 export interface InferredColumnResult<TRow = unknown> {
     columns: ColumnConfigMap<TRow>;
-    typeMap: Record<string, PrimitiveColumnType>;
+    typeMap: Record<string, ColumnType>;
 }
 export declare const FitModeEnum: {
     readonly STRETCH: "stretch";
@@ -490,6 +567,8 @@ export type FitMode = (typeof FitModeEnum)[keyof typeof FitModeEnum];
  * 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).
+ *
+ * @category Plugin Development
  */
 export interface GridPlugin {
     /** Unique plugin identifier */
@@ -509,12 +588,11 @@ export interface GridPlugin {
  * - `gridConfig` property - direct assignment of this object
  * - `columns` property - shorthand for `gridConfig.columns`
  * - `fitMode` property - shorthand for `gridConfig.fitMode`
- * - `editOn` property - shorthand for `gridConfig.editOn`
  * - Light DOM `<tbw-grid-column>` - declarative columns (merged into `columns`)
  * - Light DOM `<tbw-grid-header>` - declarative shell header (merged into `shell.header`)
  *
  * **Precedence (when same property set multiple ways):**
- * Individual props (`fitMode`, `editOn`) > `columns` prop > Light DOM > `gridConfig`
+ * Individual props (`fitMode`) > `columns` prop > Light DOM > `gridConfig`
  *
  * @example
  * ```ts
@@ -550,8 +628,18 @@ export interface GridConfig<TRow = any> {
     rowClass?: (row: TRow) => string[];
     /** Sizing mode for columns. Can also be set via `fitMode` prop. */
     fitMode?: FitMode;
-    /** Edit activation mode ('click' | 'dblClick' | false). Set to false to disable editing. Can also be set via `editOn` prop. */
-    editOn?: string | boolean;
+    /**
+     * Edit trigger mode. Requires `EditingPlugin` to be loaded.
+     *
+     * Configure via `new EditingPlugin({ editOn: 'click' })` or set on gridConfig.
+     * Plugin config takes precedence over gridConfig.
+     *
+     * - `'click'`: Single click to edit
+     * - `'dblclick'`: Double-click to edit (default)
+     * - `'manual'`: Only via programmatic API (beginEdit)
+     * - `false`: Disable editing entirely
+     */
+    editOn?: 'click' | 'dblclick' | 'manual' | false;
     /**
      * Row height in pixels for virtualization calculations.
      * The virtualization system assumes uniform row heights for performance.
@@ -638,6 +726,57 @@ export interface GridConfig<TRow = any> {
      * ```
      */
     sortHandler?: SortHandler<TRow>;
+    /**
+     * Function to extract a unique identifier from a row.
+     * Used by `updateRow()`, `getRow()`, and ID-based tracking.
+     *
+     * If not provided, falls back to `row.id` or `row._id` if present.
+     * Rows without IDs are silently skipped during map building.
+     * Only throws when explicitly calling `getRowId()` or `updateRow()` on a row without an ID.
+     *
+     * @example
+     * ```ts
+     * // Simple field
+     * getRowId: (row) => row.id
+     *
+     * // Composite key
+     * getRowId: (row) => `${row.voyageId}-${row.legNumber}`
+     *
+     * // UUID field
+     * getRowId: (row) => row.uuid
+     * ```
+     */
+    getRowId?: (row: TRow) => string;
+    /**
+     * Type-level renderer and editor defaults.
+     *
+     * Keys can be:
+     * - Built-in types: `'string'`, `'number'`, `'date'`, `'boolean'`, `'select'`
+     * - Custom types: `'currency'`, `'country'`, `'status'`, etc.
+     *
+     * Resolution order (highest priority first):
+     * 1. Column-level (`column.renderer` / `column.editor`)
+     * 2. Grid-level (`gridConfig.typeDefaults[column.type]`)
+     * 3. App-level (Angular `GridTypeRegistry`, React `GridTypeProvider`)
+     * 4. Built-in (checkbox for boolean, select for select, etc.)
+     * 5. Fallback (plain text / text input)
+     *
+     * @example
+     * ```typescript
+     * typeDefaults: {
+     *   date: { editor: myDatePickerEditor },
+     *   country: {
+     *     renderer: (ctx) => {
+     *       const span = document.createElement('span');
+     *       span.innerHTML = `<img src="/flags/${ctx.value}.svg" /> ${ctx.value}`;
+     *       return span;
+     *     },
+     *     editor: (ctx) => createCountrySelect(ctx)
+     *   }
+     * }
+     * ```
+     */
+    typeDefaults?: Record<string, TypeDefault<TRow>>;
 }
 /**
  * Sort state passed to custom sort handlers.
@@ -657,6 +796,52 @@ export interface SortState {
  * @returns Sorted array (sync) or Promise resolving to sorted array (async)
  */
 export type SortHandler<TRow = any> = (rows: TRow[], sortState: SortState, columns: ColumnConfig<TRow>[]) => TRow[] | Promise<TRow[]>;
+/**
+ * Indicates the origin of a data change.
+ * Used to prevent infinite loops in cascade update handlers.
+ *
+ * - `'user'`: Direct user interaction via EditingPlugin (typing, selecting)
+ * - `'cascade'`: Triggered by `updateRow()` in an event handler
+ * - `'api'`: External programmatic update via `grid.updateRow()`
+ *
+ * @category Data Management
+ */
+export type UpdateSource = 'user' | 'cascade' | 'api';
+/**
+ * Detail for cell-change event (emitted by core after mutation).
+ * This is an informational event that fires for ALL data mutations.
+ *
+ * @category Events
+ */
+export interface CellChangeDetail<TRow = unknown> {
+    /** The row object (after mutation) */
+    row: TRow;
+    /** Stable row identifier */
+    rowId: string;
+    /** Current index in rows array */
+    rowIndex: number;
+    /** Field that changed */
+    field: string;
+    /** Value before change */
+    oldValue: unknown;
+    /** Value after change */
+    newValue: unknown;
+    /** All changes passed to updateRow/updateRows (for context) */
+    changes: Partial<TRow>;
+    /** Origin of this change */
+    source: UpdateSource;
+}
+/**
+ * Batch update specification for updateRows().
+ *
+ * @category Data Management
+ */
+export interface RowUpdate<TRow = unknown> {
+    /** Row identifier (from getRowId) */
+    id: string;
+    /** Fields to update */
+    changes: Partial<TRow>;
+}
 /**
  * Animation behavior mode.
  * - `true` or `'on'`: Animations always enabled
@@ -759,8 +944,8 @@ export interface ShellConfig {
 export interface ShellHeaderConfig {
     /** Grid title displayed on the left (optional) */
     title?: string;
-    /** Custom toolbar buttons (rendered before tool panel toggles) */
-    toolbarButtons?: ToolbarButtonConfig[];
+    /** Custom toolbar content (rendered before tool panel toggle) */
+    toolbarContents?: ToolbarContentDefinition[];
     /**
      * Light DOM header content elements (parsed from <tbw-grid-header> children).
      * @internal Set by ConfigManager during merge
@@ -786,51 +971,33 @@ export interface ToolPanelConfig {
     persistState?: boolean;
 }
 /**
- * Toolbar button defined via config (programmatic approach).
+ * Toolbar content definition for the shell header toolbar area.
+ * Register via `registerToolbarContent()` or use light DOM `<tbw-grid-tool-buttons>`.
  *
- * The grid does NOT create buttons - developers have full control over their own buttons.
- * Provide either:
- * - `element`: A ready-made DOM element (grid appends it to toolbar)
- * - `render`: A factory function that receives a container and appends content
- *
- * For declarative HTML buttons, use light-dom instead:
- * ```html
- * <tbw-grid>
- *   <tbw-grid-header>
- *     <button slot="toolbar">My Button</button>
- *   </tbw-grid-header>
- * </tbw-grid>
+ * @example
+ * ```typescript
+ * grid.registerToolbarContent({
+ *   id: 'my-toolbar',
+ *   order: 10,
+ *   render: (container) => {
+ *     const btn = document.createElement('button');
+ *     btn.textContent = 'Refresh';
+ *     btn.onclick = () => console.log('clicked');
+ *     container.appendChild(btn);
+ *     return () => btn.remove();
+ *   },
+ * });
  * ```
  */
-export interface ToolbarButtonConfig {
-    /** Unique button ID */
+export interface ToolbarContentDefinition {
+    /** Unique content ID */
     id: string;
-    /** Tooltip / aria-label (for accessibility, used when grid generates panel toggle) */
-    label?: string;
+    /** Content factory - called once when shell header renders */
+    render: (container: HTMLElement) => void | (() => void);
+    /** Called when content is removed (for cleanup) */
+    onDestroy?: () => void;
     /** Order priority (lower = first, default: 100) */
     order?: number;
-    /**
-     * User-provided element. Grid appends it to the toolbar.
-     * User is responsible for styling, event handlers, accessibility, etc.
-     */
-    element?: HTMLElement;
-    /**
-     * Render function called once. Receives container, user appends their DOM.
-     * User is responsible for event handlers.
-     * Return a cleanup function (optional).
-     */
-    render?: (container: HTMLElement) => void | (() => void);
-}
-/**
- * Toolbar button info returned by getToolbarButtons().
- */
-export interface ToolbarButtonInfo {
-    id: string;
-    label: string;
-    /** Source of this button: 'config' | 'light-dom' | 'panel-toggle' */
-    source: 'config' | 'light-dom' | 'panel-toggle';
-    /** For panel toggles, the associated panel ID */
-    panelId?: string;
 }
 /**
  * Tool panel definition registered by plugins or consumers.
@@ -906,9 +1073,16 @@ export interface ColumnSortState {
 export interface GridColumnState {
     columns: ColumnState[];
 }
+/**
+ * Event detail for cell value commit.
+ *
+ * @category Events
+ */
 export interface CellCommitDetail<TRow = unknown> {
     /** The row object (not yet mutated if event is cancelable). */
     row: TRow;
+    /** Stable row identifier (from getRowId). */
+    rowId: string;
     /** Field name whose value changed. */
     field: string;
     /** Previous value before change. */
@@ -919,52 +1093,156 @@ export interface CellCommitDetail<TRow = unknown> {
     rowIndex: number;
     /** All rows that have at least one committed change (snapshot list). */
     changedRows: TRow[];
-    /** Indices parallel to changedRows. */
-    changedRowIndices: number[];
+    /** IDs of changed rows. */
+    changedRowIds: string[];
     /** True if this row just entered the changed set. */
     firstTimeForRow: boolean;
+    /**
+     * Update other fields in this row.
+     * Convenience wrapper for grid.updateRow(rowId, changes, 'cascade').
+     * Useful for cascade updates (e.g., calculating totals).
+     */
+    updateRow: (changes: Partial<TRow>) => void;
 }
-/** Detail payload for a committed row edit (may or may not include changes). */
+/**
+ * Detail payload for a committed row edit (may or may not include changes).
+ *
+ * @category Events
+ */
 export interface RowCommitDetail<TRow = unknown> {
     /** Row index that lost edit focus. */
     rowIndex: number;
+    /** Stable row identifier (from getRowId). */
+    rowId: string;
     /** Row object reference. */
     row: TRow;
     /** Whether any cell changes were actually committed in this row during the session. */
     changed: boolean;
     /** Current changed row collection. */
     changedRows: TRow[];
-    /** Indices of changed rows. */
-    changedRowIndices: number[];
+    /** IDs of changed rows. */
+    changedRowIds: string[];
 }
-/** Emitted when the changed rows tracking set is cleared programmatically. */
+/**
+ * Emitted when the changed rows tracking set is cleared programmatically.
+ *
+ * @category Events
+ */
 export interface ChangedRowsResetDetail<TRow = unknown> {
     /** New (empty) changed rows array after reset. */
     rows: TRow[];
-    /** Parallel indices (likely empty). */
-    indices: number[];
+    /** IDs of changed rows (likely empty). */
+    ids: string[];
 }
-/** Detail for a sort change (direction 0 indicates cleared sort). */
+/**
+ * Detail for a cell click event.
+ * Provides full context about the clicked cell including row data.
+ *
+ * @category Events
+ */
+export interface CellClickDetail<TRow = unknown> {
+    /** Zero-based row index of the clicked cell. */
+    rowIndex: number;
+    /** Zero-based column index of the clicked cell. */
+    colIndex: number;
+    /** Field name of the clicked column. */
+    field: string;
+    /** Cell value at the clicked position. */
+    value: unknown;
+    /** Full row data object. */
+    row: TRow;
+    /** The clicked cell element. */
+    cellEl: HTMLElement;
+    /** The original mouse event. */
+    originalEvent: MouseEvent;
+}
+/**
+ * Detail for a row click event.
+ * Provides context about the clicked row.
+ *
+ * @category Events
+ */
+export interface RowClickDetail<TRow = unknown> {
+    /** Zero-based row index of the clicked row. */
+    rowIndex: number;
+    /** Full row data object. */
+    row: TRow;
+    /** The clicked row element. */
+    rowEl: HTMLElement;
+    /** The original mouse event. */
+    originalEvent: MouseEvent;
+}
+/**
+ * Detail for a sort change (direction 0 indicates cleared sort).
+ *
+ * @category Events
+ */
 export interface SortChangeDetail {
     /** Sorted field key. */
     field: string;
     /** Direction: 1 ascending, -1 descending, 0 cleared. */
     direction: 1 | -1 | 0;
 }
-/** Column resize event detail containing final pixel width. */
+/**
+ * Column resize event detail containing final pixel width.
+ *
+ * @category Events
+ */
 export interface ColumnResizeDetail {
     /** Resized column field key. */
     field: string;
     /** New width in pixels. */
     width: number;
 }
-/** Fired when keyboard navigation or programmatic focus changes active cell. */
+/**
+ * Trigger type for cell activation.
+ * - `'keyboard'`: Enter key pressed on focused cell
+ * - `'pointer'`: Mouse/touch/pen click on cell
+ *
+ * @category Events
+ */
+export type CellActivateTrigger = 'keyboard' | 'pointer';
+/**
+ * Fired when a cell is activated by user interaction (Enter key or click).
+ * Unified event for both keyboard and pointer activation.
+ *
+ * @category Events
+ */
+export interface CellActivateDetail<TRow = unknown> {
+    /** Zero-based row index of the activated cell. */
+    rowIndex: number;
+    /** Zero-based column index of the activated cell. */
+    colIndex: number;
+    /** Field name of the activated column. */
+    field: string;
+    /** Cell value at the activated position. */
+    value: unknown;
+    /** Full row data object. */
+    row: TRow;
+    /** The activated cell element. */
+    cellEl: HTMLElement;
+    /** What triggered the activation. */
+    trigger: CellActivateTrigger;
+    /** The original event (KeyboardEvent for keyboard, MouseEvent/PointerEvent for pointer). */
+    originalEvent: KeyboardEvent | MouseEvent | PointerEvent;
+}
+/**
+ * @deprecated Use `CellActivateDetail` instead. Will be removed in next major version.
+ * Kept for backwards compatibility.
+ *
+ * @category Events
+ */
 export interface ActivateCellDetail {
     /** Zero-based row index now focused. */
     row: number;
     /** Zero-based column index now focused. */
     col: number;
 }
+/**
+ * Event detail for mounting external view renderers.
+ *
+ * @category Events
+ */
 export interface ExternalMountViewDetail<TRow = unknown> {
     placeholder: HTMLElement;
     spec: unknown;
@@ -975,6 +1253,11 @@ export interface ExternalMountViewDetail<TRow = unknown> {
         column: unknown;
     };
 }
+/**
+ * Event detail for mounting external editor renderers.
+ *
+ * @category Events
+ */
 export interface ExternalMountEditorDetail<TRow = unknown> {
     placeholder: HTMLElement;
     spec: unknown;
@@ -987,7 +1270,16 @@ export interface ExternalMountEditorDetail<TRow = unknown> {
         cancel: () => void;
     };
 }
+/**
+ * Maps event names to their detail payload types.
+ *
+ * @category Events
+ */
 export interface DataGridEventMap<TRow = unknown> {
+    'cell-click': CellClickDetail<TRow>;
+    'row-click': RowClickDetail<TRow>;
+    'cell-activate': CellActivateDetail<TRow>;
+    'cell-change': CellChangeDetail<TRow>;
     'cell-commit': CellCommitDetail<TRow>;
     'row-commit': RowCommitDetail<TRow>;
     'changed-rows-reset': ChangedRowsResetDetail<TRow>;
@@ -995,12 +1287,28 @@ export interface DataGridEventMap<TRow = unknown> {
     'mount-external-editor': ExternalMountEditorDetail<TRow>;
     'sort-change': SortChangeDetail;
     'column-resize': ColumnResizeDetail;
+    /** @deprecated Use 'cell-activate' instead */
     'activate-cell': ActivateCellDetail;
     'column-state-change': GridColumnState;
 }
+/**
+ * Extracts the event detail type for a given event name.
+ *
+ * @category Events
+ */
 export type DataGridEventDetail<K extends keyof DataGridEventMap<unknown>, TRow = unknown> = DataGridEventMap<TRow>[K];
+/**
+ * Custom event type for DataGrid events with typed detail payload.
+ *
+ * @category Events
+ */
 export type DataGridCustomEvent<K extends keyof DataGridEventMap<unknown>, TRow = unknown> = CustomEvent<DataGridEventMap<TRow>[K]>;
 export type EditorContext<T = unknown> = ColumnEditorContext<T, unknown>;
+/**
+ * Template evaluation context for dynamic templates.
+ *
+ * @category Plugin Development
+ */
 export interface EvalContext {
     value: unknown;
     row: Record<string, unknown> | null;