@agile-team/mach-table 0.4.1 → 0.13.0

package/dist/index.d.ts

@@ -39,25 +39,30 @@ interface RowNode<TData = any> {
     groupKey?: string;
     leafNodes?: RowNode<TData>[];
     aggValues?: Record<string, any>;
+    /** Lazy tree request state. These fields are read-only from application code. */
+    treeLoading?: boolean;
+    treeChildrenLoaded?: boolean;
+    treeLoadError?: unknown;
 }
 
-declare const EVENT_TYPES: readonly ["gridReady", "gridDestroyed", "modelUpdated", "cellClicked", "cellDoubleClicked", "cellContextMenu", "rowClicked", "rowDoubleClicked", "selectionChanged", "sortChanged", "filterChanged", "columnResized", "columnMoved", "columnVisibilityChanged", "cellValueChanged", "cellEditingStarted", "cellEditingStopped", "detailToggled", "rowDragEnd", "rangeSelectionChanged", "paginationChanged", "displayedColumnsChanged", "gridError"];
+declare const EVENT_TYPES: readonly ["gridReady", "gridDestroyed", "modelUpdated", "cellClicked", "cellDoubleClicked", "cellContextMenu", "rowClicked", "rowDoubleClicked", "selectionChanged", "sortChanged", "filterChanged", "columnResized", "columnMoved", "columnVisibilityChanged", "cellValueChanged", "cellEditingStarted", "cellEditingStopped", "rowEditingStarted", "rowEditingStopped", "detailToggled", "treeChildrenLoaded", "treeChildrenLoadFailed", "rowDragEnd", "rangeSelectionChanged", "paginationChanged", "displayedColumnsChanged", "gridError", "dirtyStateChanged"];
 type GridEventType = (typeof EVENT_TYPES)[number];
-interface GridEventBase {
+type GridErrorCode = "DATA_SOURCE_ERROR" | "DATA_INTEGRITY_ERROR" | "VALIDATION_ERROR" | "RENDERER_ERROR" | "EDITOR_ERROR" | "FEATURE_ERROR" | "STATE_ERROR" | "EVENT_HANDLER_ERROR" | "GRID_ERROR";
+interface GridEventBase<TData = any> {
     type: GridEventType;
-    api: GridApi<any>;
+    api: GridApi<TData>;
 }
-interface GridReadyEvent extends GridEventBase {
+interface GridReadyEvent<TData = any> extends GridEventBase<TData> {
     type: "gridReady";
 }
-interface GridDestroyedEvent extends GridEventBase {
+interface GridDestroyedEvent<TData = any> extends GridEventBase<TData> {
     type: "gridDestroyed";
 }
-interface ModelUpdatedEvent extends GridEventBase {
+interface ModelUpdatedEvent<TData = any> extends GridEventBase<TData> {
     type: "modelUpdated";
     rowCount: number;
 }
-interface CellClickEvent<TData = any, TValue = any> extends GridEventBase {
+interface CellClickEvent<TData = any, TValue = any> extends GridEventBase<TData> {
     type: "cellClicked";
     event: MouseEvent;
     rowNode: RowNode<TData>;
@@ -66,7 +71,7 @@ interface CellClickEvent<TData = any, TValue = any> extends GridEventBase {
     colDef: ColDef<TData, TValue>;
     value: TValue;
 }
-interface CellDoubleClickEvent<TData = any, TValue = any> extends GridEventBase {
+interface CellDoubleClickEvent<TData = any, TValue = any> extends GridEventBase<TData> {
     type: "cellDoubleClicked";
     event: MouseEvent;
     rowNode: RowNode<TData>;
@@ -75,7 +80,7 @@ interface CellDoubleClickEvent<TData = any, TValue = any> extends GridEventBase
     colDef: ColDef<TData, TValue>;
     value: TValue;
 }
-interface CellContextMenuEvent<TData = any, TValue = any> extends GridEventBase {
+interface CellContextMenuEvent<TData = any, TValue = any> extends GridEventBase<TData> {
     type: "cellContextMenu";
     event: MouseEvent;
     rowNode: RowNode<TData>;
@@ -84,42 +89,42 @@ interface CellContextMenuEvent<TData = any, TValue = any> extends GridEventBase
     colDef: ColDef<TData, TValue>;
     value: TValue;
 }
-interface RowClickEvent<TData = any> extends GridEventBase {
+interface RowClickEvent<TData = any> extends GridEventBase<TData> {
     type: "rowClicked" | "rowDoubleClicked";
     event: MouseEvent;
     rowNode: RowNode<TData>;
     rowIndex: number;
 }
-interface SelectionChangedEvent<TData = any> extends GridEventBase {
+interface SelectionChangedEvent<TData = any> extends GridEventBase<TData> {
     type: "selectionChanged";
     selectedNodes: RowNode<TData>[];
     selectedRows: TData[];
 }
-interface SortChangedEvent extends GridEventBase {
+interface SortChangedEvent<TData = any> extends GridEventBase<TData> {
     type: "sortChanged";
     sortModel: SortModel;
 }
-interface FilterChangedEvent extends GridEventBase {
+interface FilterChangedEvent<TData = any> extends GridEventBase<TData> {
     type: "filterChanged";
     filterModel: FilterModel;
 }
-interface ColumnResizedEvent extends GridEventBase {
+interface ColumnResizedEvent<TData = any> extends GridEventBase<TData> {
     type: "columnResized";
     colId: string;
     width: number;
     finished: boolean;
 }
-interface ColumnMovedEvent extends GridEventBase {
+interface ColumnMovedEvent<TData = any> extends GridEventBase<TData> {
     type: "columnMoved";
     colId: string;
     toIndex: number;
 }
-interface ColumnVisibilityChangedEvent extends GridEventBase {
+interface ColumnVisibilityChangedEvent<TData = any> extends GridEventBase<TData> {
     type: "columnVisibilityChanged";
     colId: string;
     visible: boolean;
 }
-interface CellValueChangedEvent<TData = any, TValue = any> extends GridEventBase {
+interface CellValueChangedEvent<TData = any, TValue = any> extends GridEventBase<TData> {
     type: "cellValueChanged";
     oldValue: TValue;
     newValue: TValue;
@@ -129,13 +134,13 @@ interface CellValueChangedEvent<TData = any, TValue = any> extends GridEventBase
     colDef: ColDef<TData, TValue>;
     data: TData;
 }
-interface CellEditingStartedEvent<TData = any> extends GridEventBase {
+interface CellEditingStartedEvent<TData = any> extends GridEventBase<TData> {
     type: "cellEditingStarted";
     rowIndex: number;
     colId: string;
     rowNode: RowNode<TData>;
 }
-interface CellEditingStoppedEvent<TData = any> extends GridEventBase {
+interface CellEditingStoppedEvent<TData = any> extends GridEventBase<TData> {
     type: "cellEditingStopped";
     rowIndex: number;
     colId: string;
@@ -143,68 +148,109 @@ interface CellEditingStoppedEvent<TData = any> extends GridEventBase {
     oldValue: any;
     newValue: any;
 }
-interface DetailToggledEvent<TData = any> extends GridEventBase {
+interface RowEditChange {
+    colId: string;
+    oldValue: unknown;
+    newValue: unknown;
+}
+interface RowEditingStartedEvent<TData = any> extends GridEventBase<TData> {
+    type: "rowEditingStarted";
+    rowIndex: number;
+    rowNode: RowNode<TData>;
+    data: TData;
+}
+interface RowEditingStoppedEvent<TData = any> extends GridEventBase<TData> {
+    type: "rowEditingStopped";
+    rowIndex: number;
+    rowNode: RowNode<TData>;
+    data: TData;
+    cancelled: boolean;
+    changes: RowEditChange[];
+}
+interface DetailToggledEvent<TData = any> extends GridEventBase<TData> {
     type: "detailToggled";
     rowId: string;
     rowNode: RowNode<TData>;
     expanded: boolean;
 }
+interface TreeChildrenLoadedEvent<TData = any> extends GridEventBase<TData> {
+    type: "treeChildrenLoaded";
+    rowId: string;
+    rowNode: RowNode<TData>;
+    children: readonly TData[];
+}
+interface TreeChildrenLoadFailedEvent<TData = any> extends GridEventBase<TData> {
+    type: "treeChildrenLoadFailed";
+    rowId: string;
+    rowNode: RowNode<TData>;
+    error: unknown;
+}
 interface GridCellRange {
     row1: number;
     row2: number;
     colId1: string;
     colId2: string;
 }
-interface RangeSelectionChangedEvent extends GridEventBase {
+interface RangeSelectionChangedEvent<TData = any> extends GridEventBase<TData> {
     type: "rangeSelectionChanged";
     range: GridCellRange | null;
 }
-interface RowDragEndEvent<TData = any> extends GridEventBase {
+interface RowDragEndEvent<TData = any> extends GridEventBase<TData> {
     type: "rowDragEnd";
     rowNode: RowNode<TData>;
     fromIndex: number;
     toIndex: number;
 }
-interface PaginationChangedEvent extends GridEventBase {
+interface PaginationChangedEvent<TData = any> extends GridEventBase<TData> {
     type: "paginationChanged";
     page: number;
     pageSize: number;
     pageCount: number;
     total: number;
 }
-interface DisplayedColumnsChangedEvent extends GridEventBase {
+interface DisplayedColumnsChangedEvent<TData = any> extends GridEventBase<TData> {
     type: "displayedColumnsChanged";
 }
-interface GridErrorEvent extends GridEventBase {
+interface GridErrorEvent<TData = any> extends GridEventBase<TData> {
     type: "gridError";
+    code: GridErrorCode;
     error: unknown;
     source: string;
     context?: Record<string, unknown>;
 }
+interface DirtyStateChangedEvent<TData = any> extends GridEventBase<TData> {
+    type: "dirtyStateChanged";
+    dirtyRowIds: string[];
+}
 interface GridEventMap<TData = any> {
-    gridReady: GridReadyEvent;
-    gridDestroyed: GridDestroyedEvent;
-    modelUpdated: ModelUpdatedEvent;
+    gridReady: GridReadyEvent<TData>;
+    gridDestroyed: GridDestroyedEvent<TData>;
+    modelUpdated: ModelUpdatedEvent<TData>;
     cellClicked: CellClickEvent<TData>;
     cellDoubleClicked: CellDoubleClickEvent<TData>;
     cellContextMenu: CellContextMenuEvent<TData>;
     rowClicked: RowClickEvent<TData>;
     rowDoubleClicked: RowClickEvent<TData>;
     selectionChanged: SelectionChangedEvent<TData>;
-    sortChanged: SortChangedEvent;
-    filterChanged: FilterChangedEvent;
-    columnResized: ColumnResizedEvent;
-    columnMoved: ColumnMovedEvent;
-    columnVisibilityChanged: ColumnVisibilityChangedEvent;
+    sortChanged: SortChangedEvent<TData>;
+    filterChanged: FilterChangedEvent<TData>;
+    columnResized: ColumnResizedEvent<TData>;
+    columnMoved: ColumnMovedEvent<TData>;
+    columnVisibilityChanged: ColumnVisibilityChangedEvent<TData>;
     cellValueChanged: CellValueChangedEvent<TData>;
     cellEditingStarted: CellEditingStartedEvent<TData>;
     cellEditingStopped: CellEditingStoppedEvent<TData>;
+    rowEditingStarted: RowEditingStartedEvent<TData>;
+    rowEditingStopped: RowEditingStoppedEvent<TData>;
     detailToggled: DetailToggledEvent<TData>;
+    treeChildrenLoaded: TreeChildrenLoadedEvent<TData>;
+    treeChildrenLoadFailed: TreeChildrenLoadFailedEvent<TData>;
     rowDragEnd: RowDragEndEvent<TData>;
-    rangeSelectionChanged: RangeSelectionChangedEvent;
-    paginationChanged: PaginationChangedEvent;
-    displayedColumnsChanged: DisplayedColumnsChangedEvent;
-    gridError: GridErrorEvent;
+    rangeSelectionChanged: RangeSelectionChangedEvent<TData>;
+    paginationChanged: PaginationChangedEvent<TData>;
+    displayedColumnsChanged: DisplayedColumnsChangedEvent<TData>;
+    gridError: GridErrorEvent<TData>;
+    dirtyStateChanged: DirtyStateChangedEvent<TData>;
 }
 
 declare const DEFAULT_LOCALE: {
@@ -265,6 +311,31 @@ declare function matchLocaleKey(match: string): RgLocaleKey;
 declare function formatText(template: string, n: number | string): string;
 declare function formatTwo(template: string, a: number | string, b: number | string): string;
 
+/** Serializable snapshot of user-visible grid state. */
+interface GridState {
+    /** State schema version, independent from the package version. */
+    version: 1;
+    columns: ColumnState[];
+    sortModel: SortModel;
+    filterModel: FilterModel;
+    quickFilterText: string | null;
+    pagination: {
+        enabled: boolean;
+        page: number;
+        pageSize: number;
+    };
+    selectedRowIds: string[];
+    expandedRowIds: string[];
+    expandedGroupIds: string[];
+}
+type GridStateSection = "columns" | "sort" | "filter" | "pagination" | "selection" | "expansion";
+interface ApplyGridStateOptions {
+    /** Applies all sections when omitted. */
+    sections?: readonly GridStateSection[];
+    /** Emit the standard sort/filter/pagination events after restoration. */
+    emitEvents?: boolean;
+}
+
 interface ColumnStateStore {
     load(key: string): ColumnState[] | null | Promise<ColumnState[] | null>;
     save(key: string, state: ColumnState[]): void | Promise<void>;
@@ -279,6 +350,11 @@ interface GridFeatureContext<TData = any> {
     readonly root: HTMLElement;
     getOptions(): Readonly<ResolvedGridOptions<TData>>;
     addEventListener<K extends keyof GridEventMap<TData>>(type: K, listener: (event: GridEventMap<TData>[K]) => void): () => void;
+    /** Registers cleanup even when setup later throws or the feature is hot-replaced. */
+    onCleanup(cleanup: () => void): void;
+    addManagedDomListener(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): () => void;
+    setManagedTimeout(handler: () => void, delayMs: number): ReturnType<typeof setTimeout>;
+    createAbortController(): AbortController;
     reportError(error: unknown, source: string, context?: Record<string, unknown>): void;
 }
 /** Composable extension point; feature instances are scoped to one grid. */
@@ -291,7 +367,8 @@ interface GridFeature<TData = any> {
  * Safe overlay content. Strings render as text unless
  * `allowUnsafeOverlayHtml` is explicitly enabled.
  */
-type OverlayTemplate = string | HTMLElement | (() => string | HTMLElement);
+type OverlayContent = string | HTMLElement | ICellRendererResult;
+type OverlayTemplate = OverlayContent | (() => OverlayContent);
 type StatusBarPanel = "rowCount" | "selectedRowCount" | "rangeAggregate";
 interface StatusBarConfig {
     panels?: StatusBarPanel[];
@@ -314,13 +391,37 @@ type EventHandlers<TData = any> = {
 };
 type RowSelectionMode = "none" | "single" | "multiple";
 type GridSize = "compact" | "normal" | "large";
+type ColumnLayoutMode = "normal" | "fit";
 type ThemeMode = "light" | "dark" | "auto";
+type GridEditType = "cell" | "fullRow";
+type EditableIndicator = "hover" | "always" | "none";
+interface RowEditValidationParams<TData = any> {
+    data: TData;
+    node: RowNode<TData>;
+    /** Draft values keyed by colId, including unchanged editable cells. */
+    values: Readonly<Record<string, unknown>>;
+    changes: readonly RowEditChange[];
+    api: GridApi<TData>;
+}
+type RowEditValidationResult = true | null | undefined | string | Readonly<Record<string, string>>;
 interface DetailRowRendererParams<TData = any> {
     data: TData | null;
     node: RowNode<TData>;
     api: GridApi<TData>;
 }
+interface TreeDataLoadParams<TData = any> {
+    data: TData;
+    node: RowNode<TData>;
+    api: GridApi<TData>;
+    signal: AbortSignal;
+}
 interface PaginationConfig {
+    /** `server` displays the supplied page as-is and uses `total` for navigation. */
+    mode?: "client" | "server";
+    /** Controlled current page for server mode. */
+    page?: number;
+    /** Total rows across all server pages. */
+    total?: number;
     pageSize?: number;
     pageSizeOptions?: number[];
     showTotal?: boolean;
@@ -334,14 +435,34 @@ interface WatermarkConfig {
     gap?: number;
     angle?: number;
 }
+interface ActionPolicyContext<TData = any> {
+    /** Stable business action identifier, for example `order.delete`. */
+    actionId?: string;
+    permissions: readonly string[];
+    message?: string;
+    params: CellRendererParams<TData>;
+}
+/**
+ * Application-wide UI action policy. This centralises permission, confirmation
+ * and error handling while the backend remains the final security boundary.
+ */
+interface ActionPolicy<TData = any> {
+    canAccess?(context: ActionPolicyContext<TData>): boolean;
+    confirm?(context: ActionPolicyContext<TData>): boolean | Promise<boolean>;
+    onError?(error: unknown, context: ActionPolicyContext<TData>): void;
+}
 interface GridOptions<TData = any> extends EventHandlers<TData> {
     columnDefs?: (ColDef<TData> | ColDefGroup<TData>)[] | null;
     rowData?: TData[] | null;
     defaultColDef?: Partial<ColDef<TData>>;
+    /** Reusable semantic column definitions referenced through `colDef.type`. */
+    columnTypes?: Readonly<Record<string, Partial<ColDef<TData>>>>;
     getRowId?: (params: GetRowIdParams<TData>) => string;
     rowHeight?: number;
     headerHeight?: number;
     rowBuffer?: number;
+    /** `fit` continuously fills the container without grid-ready glue code. */
+    columnLayout?: ColumnLayoutMode;
     rowSelection?: RowSelectionMode;
     multiSort?: boolean;
     size?: GridSize;
@@ -359,8 +480,18 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
     columnStateStore?: ColumnStateStore;
     aggFuncs?: Record<string, (values: any[]) => any>;
     components?: GridComponents;
+    /** Shared policy consumed by action column helpers. */
+    actionPolicy?: ActionPolicy<TData>;
     features?: readonly GridFeature<TData>[];
+    /** State restored atomically after columns and initial rows are available. */
+    initialState?: GridState;
     locale?: RgLocale;
+    /** Cell editing is isolated; fullRow stages every editable cell and commits them together. */
+    editType?: GridEditType;
+    /** Visibility of the subtle pencil affordance on editable cells. */
+    editableIndicator?: EditableIndicator;
+    /** Cross-field full-row validation. Return a message or a colId -> message map. */
+    rowEditValidator?: (params: RowEditValidationParams<TData>) => RowEditValidationResult | Promise<RowEditValidationResult>;
     singleClickEdit?: boolean;
     manualSorting?: boolean;
     manualFiltering?: boolean;
@@ -372,11 +503,17 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
     }) => string;
     treeData?: boolean;
     childrenKey?: string;
+    /** Marks rows that can load children even when `childrenKey` is currently empty. */
+    isTreeRowExpandable?: (params: Omit<TreeDataLoadParams<TData>, "signal">) => boolean;
+    /** Loads children once on first expansion; use the API retry/force methods to reload. */
+    loadTreeChildren?: (params: TreeDataLoadParams<TData>) => Promise<readonly TData[]>;
     autoCheckedChildren?: boolean;
     defaultExpandAll?: boolean;
     indexOffset?: number;
     applyRowDrag?: boolean;
     undoStackSize?: number;
+    /** Milliseconds used to coalesce applyTransactionAsync calls. */
+    asyncTransactionWaitMillis?: number;
     getRowHeight?: (params: GetRowHeightParams<TData>) => number;
     pinnedTopRowData?: TData[] | null;
     pinnedBottomRowData?: TData[] | null;
@@ -395,10 +532,20 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
     datasource?: GridDatasource<TData>;
     blockSize?: number;
     infiniteBufferRows?: number;
+    /** Number of automatic retries after an infinite datasource request fails. */
+    datasourceRetryCount?: number;
+    /** Base retry delay in milliseconds. Retries use capped exponential backoff. */
+    datasourceRetryDelay?: number;
     suppressCellFocus?: boolean;
     suppressRowHoverHighlight?: boolean;
     suppressNoRowsOverlay?: boolean;
     suppressHeaderFocus?: boolean;
+    /** Accessible name applied to the element with role="grid"/"treegrid". */
+    ariaLabel?: string;
+    /** ID of an external element that labels the grid. Takes precedence over ariaLabel. */
+    ariaLabelledBy?: string;
+    /** ID of an external element that provides additional grid instructions. */
+    ariaDescribedBy?: string;
     loading?: boolean;
     overlayNoRowsTemplate?: OverlayTemplate;
     overlayLoadingTemplate?: OverlayTemplate;
@@ -410,10 +557,12 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     columnDefs: (ColDef<TData> | ColDefGroup<TData>)[];
     rowData: TData[];
     defaultColDef: Partial<ColDef<TData>>;
+    columnTypes: Readonly<Record<string, Partial<ColDef<TData>>>>;
     getRowId?: (params: GetRowIdParams<TData>) => string;
     rowHeight: number;
     headerHeight: number;
     rowBuffer: number;
+    columnLayout: ColumnLayoutMode;
     rowSelection: RowSelectionMode;
     multiSort: boolean;
     size: GridSize;
@@ -431,8 +580,13 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     columnStateStore?: ColumnStateStore;
     aggFuncs?: Record<string, (values: any[]) => any>;
     components?: GridComponents;
+    actionPolicy?: ActionPolicy<TData>;
     features: readonly GridFeature<TData>[];
+    initialState?: GridState;
     locale: RgLocale;
+    editType: GridEditType;
+    editableIndicator: EditableIndicator;
+    rowEditValidator?: (params: RowEditValidationParams<TData>) => RowEditValidationResult | Promise<RowEditValidationResult>;
     singleClickEdit: boolean;
     manualSorting: boolean;
     manualFiltering: boolean;
@@ -444,15 +598,21 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     }) => string;
     treeData: boolean;
     childrenKey: string;
+    isTreeRowExpandable?: (params: Omit<TreeDataLoadParams<TData>, "signal">) => boolean;
+    loadTreeChildren?: (params: TreeDataLoadParams<TData>) => Promise<readonly TData[]>;
     autoCheckedChildren: boolean;
     defaultExpandAll: boolean;
     indexOffset: number;
     applyRowDrag: boolean;
     undoStackSize: number;
+    asyncTransactionWaitMillis: number;
     getRowHeight?: (params: GetRowHeightParams<TData>) => number;
     pinnedTopRowData: TData[];
     pinnedBottomRowData: TData[];
     paginationEnabled: boolean;
+    paginationMode: "client" | "server";
+    paginationPage: number;
+    paginationTotal: number;
     paginationPageSize: number;
     paginationPageSizeOptions: number[];
     paginationShowTotal: boolean;
@@ -473,10 +633,15 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     datasource?: GridDatasource<TData>;
     blockSize: number;
     infiniteBufferRows: number;
+    datasourceRetryCount: number;
+    datasourceRetryDelay: number;
     suppressCellFocus: boolean;
     suppressRowHoverHighlight: boolean;
     suppressNoRowsOverlay: boolean;
     suppressHeaderFocus: boolean;
+    ariaLabel: string;
+    ariaLabelledBy: string;
+    ariaDescribedBy: string;
     loading: boolean;
     overlayNoRowsTemplate: OverlayTemplate;
     overlayLoadingTemplate: OverlayTemplate;
@@ -515,9 +680,63 @@ interface RowTransaction<TData = any> {
     remove?: TData[];
     update?: TData[];
 }
+interface GridCellChange {
+    colId: string;
+    originalValue: unknown;
+    value: unknown;
+}
+interface GridChange<TData = any> {
+    rowId: string;
+    data: TData;
+    cells: GridCellChange[];
+}
+interface GridDiagnosticError {
+    code: GridErrorCode;
+    source: string;
+    message: string;
+    timestamp: number;
+    context?: Record<string, unknown>;
+}
+interface ColumnWorkbenchItem {
+    colId: string;
+    label: string;
+    visible: boolean;
+    pinned: "left" | "right" | null;
+    width: number;
+    movable: boolean;
+    hideable: boolean;
+}
+interface GridDiagnostics {
+    gridId: number;
+    version: string;
+    destroyed: boolean;
+    infinite: boolean;
+    loading: boolean;
+    rowCount: number;
+    renderedRowCount: number;
+    columnCount: number;
+    selectedRowCount: number;
+    dirtyRowCount: number;
+    recentErrors: readonly GridDiagnosticError[];
+}
+interface SaveChangesResult {
+    /** Omit to acknowledge every submitted row; return a subset for partial batch success. */
+    savedRowIds?: readonly string[];
+}
+type SaveChangesHandler<TData = any> = (changes: readonly GridChange<TData>[]) => void | SaveChangesResult | Promise<void | SaveChangesResult>;
 interface GridApi<TData = any> {
+    /** Resolves after the first layout frame and gridReady emission. */
+    whenReady(): Promise<GridApi<TData>>;
+    /** Reads the currently resolved value after application, preset and table overrides. */
+    getGridOption<K extends keyof GridOptions<TData>>(key: K): GridOptions<TData>[K];
+    /** Typed shorthand for updating one runtime option. */
+    setGridOption<K extends keyof GridOptions<TData>>(key: K, value: GridOptions<TData>[K]): void;
     setRowData(rows: TData[] | null | undefined): void;
     applyTransaction(transaction: RowTransaction<TData>): void;
+    /** Coalesces rapid transactions and refreshes the row pipeline once per batch. */
+    applyTransactionAsync(transaction: RowTransaction<TData>): Promise<void>;
+    /** Immediately applies transactions currently waiting in the async queue. */
+    flushAsyncTransactions(): void;
     getColumnDefs(): (ColDef<TData> | ColDefGroup<TData>)[] | null;
     setColumnDefs(colDefs: (ColDef<TData> | ColDefGroup<TData>)[] | null | undefined): void;
     getColumnState(): ColumnState[];
@@ -555,6 +774,12 @@ interface GridApi<TData = any> {
     isRowExpanded(rowId: string): boolean;
     expandAllDetails(): void;
     collapseAllDetails(): void;
+    /** Loads and caches lazy tree children. Concurrent calls for one row are deduplicated. */
+    loadTreeChildren(rowId: string, options?: {
+        force?: boolean;
+    }): Promise<readonly TData[]>;
+    retryTreeChildren(rowId: string): Promise<readonly TData[]>;
+    isTreeRowLoading(rowId: string): boolean;
     toggleRowGroup(groupId: string): boolean;
     isGroupExpanded(groupId: string): boolean;
     expandAllGroups(): void;
@@ -567,6 +792,12 @@ interface GridApi<TData = any> {
     redo(): boolean;
     canUndo(): boolean;
     canRedo(): boolean;
+    getDirtyRowIds(): string[];
+    getChanges(): GridChange<TData>[];
+    markChangesSaved(rowIds?: readonly string[]): void;
+    /** Saves a stable snapshot; supports partial success and preserves edits made in flight. */
+    saveChanges(handler: SaveChangesHandler<TData>, rowIds?: readonly string[]): Promise<GridChange<TData>[]>;
+    rollbackChanges(rowIds?: readonly string[]): boolean;
     setPinnedTopRowData(rows: TData[] | null): void;
     getPinnedTopRowData(): TData[];
     setPinnedBottomRowData(rows: TData[] | null): void;
@@ -574,6 +805,11 @@ interface GridApi<TData = any> {
     getRangeSelection(): GridCellRange | null;
     clearRangeSelection(): void;
     copyRangeToClipboard(): Promise<boolean>;
+    /** Opens the built-in searchable column workbench. */
+    openColumnWorkbench(anchor?: HTMLElement): void;
+    closeColumnWorkbench(): void;
+    getColumnWorkbenchItems(): ColumnWorkbenchItem[];
+    /** @deprecated Use openColumnWorkbench. Kept during the 0.x compatibility window. */
     openColumnPanel(anchor?: HTMLElement): void;
     refreshLayout(): void;
     isInfinite(): boolean;
@@ -593,10 +829,22 @@ interface GridApi<TData = any> {
         colId: string;
         keyPress?: string;
     }): boolean;
+    /** Starts staged editing for every editable cell in one displayed row. */
+    startEditingRow(rowIndex: number): boolean;
+    /** Returns whether any row, or the requested displayed row, is in full-row edit mode. */
+    isRowEditing(rowIndex?: number): boolean;
     stopEditing(cancel?: boolean): void;
+    /** Stops editing and resolves after synchronous or asynchronous validation. */
+    stopEditingAsync(cancel?: boolean): Promise<boolean>;
+    /** Explicit full-row counterpart; aliases stopEditingAsync when a row is active. */
+    stopEditingRow(cancel?: boolean): Promise<boolean>;
     refreshCells(): void;
     updateOptions(options: Partial<GridOptions<TData>>): void;
     getDataAsCsv(params?: CsvExportParams): string;
+    getState(): GridState;
+    applyState(state: GridState, options?: ApplyGridStateOptions): void;
+    /** Lightweight runtime snapshot suitable for support logs and health panels. */
+    getDiagnostics(): GridDiagnostics;
     setOverlay(type: "loading" | "noRows" | null): void;
     hideOverlays(): void;
     addEventListener<K extends GridEventType>(eventType: K, listener: (event: GridEventMap<TData>[K]) => void): () => void;
@@ -770,6 +1018,8 @@ interface ColDef<TData = any, TValue = any> {
     minWidth?: number;
     maxWidth?: number;
     flex?: number;
+    /** Excludes the column from `columnLayout: "fit"` scaling. */
+    suppressSizeToFit?: boolean;
     hide?: boolean;
     pinned?: PinnedDirection | boolean;
     sortable?: boolean;
@@ -792,7 +1042,7 @@ interface ColDef<TData = any, TValue = any> {
     autoRowSpan?: boolean;
     colSpan?: (params: CellClassParams<TData, TValue>) => number;
     autoHeight?: boolean;
-    validate?: (newValue: TValue, params: ValueSetterParams<TData, TValue>) => string | true | null | undefined;
+    validate?: (newValue: TValue, params: ValueSetterParams<TData, TValue>) => string | true | null | undefined | Promise<string | true | null | undefined>;
     rowDrag?: boolean;
     valueGetter?: (params: ValueGetterParams<TData, TValue>) => TValue;
     valueSetter?: (params: ValueSetterParams<TData, TValue>) => boolean;
@@ -801,7 +1051,8 @@ interface ColDef<TData = any, TValue = any> {
     cellRendererParams?: Record<string, any>;
     cellClass?: CellClassRule;
     comparator?: (valueA: any, valueB: any, nodeA: RowNode<TData>, nodeB: RowNode<TData>) => number;
-    type?: string;
+    /** Named column type(s), resolved left-to-right before this column definition. */
+    type?: string | readonly string[];
     initialSort?: SortDirection;
     onCellClick?: (event: CellClickEvent<TData, TValue>) => void;
     onCellDoubleClick?: (event: CellDoubleClickEvent<TData, TValue>) => void;
@@ -884,7 +1135,7 @@ declare class ColumnModel {
     cycleSort(column: Column, additive: boolean): void;
 }
 
-type RowModelContext = Pick<GridCore<any>, "bodyRenderer" | "columnModel" | "emit" | "getApi" | "getCellValue" | "getLocaleText" | "headerRenderer" | "isDestroyed" | "nextId" | "options" | "relayout" | "reportError" | "selectionService" | "skeleton" | "undoService">;
+type RowModelContext = Pick<GridCore<any>, "bodyRenderer" | "changeTracker" | "columnModel" | "emit" | "getApi" | "getCellValue" | "getLocaleText" | "headerRenderer" | "isDestroyed" | "nextId" | "options" | "relayout" | "reportError" | "selectionService" | "skeleton" | "undoService">;
 declare class RowModel<TData = any> {
     private core;
     private all;
@@ -904,9 +1155,12 @@ declare class RowModel<TData = any> {
     private infiniteLoading;
     private infiniteSeq;
     private infiniteAbort;
+    private infiniteRetryTimer;
     private infinitePendingResolve;
     private treeDepth;
     private rowSequence;
+    private treeLoadControllers;
+    private treeLoadPromises;
     constructor(core: RowModelContext);
     resolveRowId(data: TData, index: number, fallback: string): string;
     get isTree(): boolean;
@@ -927,7 +1181,13 @@ declare class RowModel<TData = any> {
     getChildrenIds(id: string): string[];
     getChildrenCount(id: string): number;
     hasChildren(id: string): boolean;
-    applyTransaction(transaction: RowTransaction<TData>): void;
+    isTreeRowLoading(id: string): boolean;
+    private cancelTreeLoads;
+    loadTreeChildren(id: string, force?: boolean): Promise<readonly TData[]>;
+    private replaceTreeChildren;
+    private validateTreeChildren;
+    applyTransaction(transaction: RowTransaction<TData>, refresh?: boolean): void;
+    applyTransactions(transactions: readonly RowTransaction<TData>[]): void;
     private buildChildNodes;
     private reindexAll;
     setFilterModel(filterModel: FilterModel | null): boolean;
@@ -948,6 +1208,7 @@ declare class RowModel<TData = any> {
     getPipelineRows(): RowNode<TData>[];
     setPage(page: number, silent?: boolean): void;
     setPageSize(size: number): void;
+    restorePagination(page: number, pageSize: number): void;
     setPaginationEnabled(enabled: boolean): void;
     onPaginationOptionsChanged(): void;
     private emitPaginationChanged;
@@ -959,6 +1220,9 @@ declare class RowModel<TData = any> {
     private buildGrouped;
     isRowExpandable(node: RowNode<TData>): boolean;
     isRowExpanded(id: string): boolean;
+    getExpandedRowIds(): string[];
+    getExpandedGroupIds(): string[];
+    restoreExpansion(rowIds: readonly string[], groupIds: readonly string[]): void;
     expandRow(id: string): boolean;
     collapseRow(id: string): boolean;
     toggleDetail(id: string): boolean;
@@ -996,6 +1260,7 @@ declare class SelectionService {
     getSelectedNodes(): RowNode<any>[];
     getSelectedRows(): any[];
     getSelectedIds(): string[];
+    restoreSelection(ids: readonly string[]): void;
     onRowsRebuilt(preserveIds: boolean): void;
     getGroupSelectionState(groupNode: RowNode<any>): {
         all: boolean;
@@ -1065,22 +1330,61 @@ declare class KeyboardService {
     private onCut;
     private onPaste;
     private onKeyDown;
+    private handleSelectAll;
+    private handleHistoryShortcut;
+    private handleRangeCommand;
+    private focusFirstCell;
+    private handleFocusedKey;
+    private resolveKeyPosition;
+    private movePosition;
+    private validSkippedRow;
+    private movePage;
+    private activateEditor;
+    private toggleFocusedRow;
+    private moveToEditable;
 }
 
-type EditingContext = Pick<GridCore<any>, "bodyRenderer" | "emit" | "getApi" | "getCellValue" | "keyboardService" | "reportError" | "resolveCellEditor" | "rowModel" | "setCellValue">;
+type EditingContext = Pick<GridCore<any>, "bodyRenderer" | "columnModel" | "emit" | "getApi" | "getCellValue" | "keyboardService" | "notifyCellValueChanged" | "options" | "reportError" | "resolveCellEditor" | "rowModel" | "setCellValue" | "statusBarService" | "summaryRenderer" | "undoService" | "writeValue">;
 declare class EditingService {
     private core;
-    private editing;
+    private cellEditing;
+    private rowEditing;
+    private stopPromise;
+    private stopToken;
     constructor(core: EditingContext);
     isEditing(rowIndex?: number, colId?: string): boolean;
+    isCellEditing(): boolean;
+    isRowEditing(rowIndex?: number): boolean;
     isEditable(node: RowNode<any>, column: Column): boolean;
     start(rowIndex: number, column: Column, keyPress?: string | null): boolean;
+    startRow(rowIndex: number, preferredColId?: string): boolean;
+    /** Called by BodyRenderer so row editors survive horizontal/vertical virtualization. */
+    renderEditor(rowIndex: number, node: RowNode<any>, column: Column, cell: HTMLElement): boolean;
+    /** Captures a staged value before a pooled/virtual cell is reused. */
+    releaseCell(rowIndex: number, colId: string, cell: HTMLElement): void;
     stop(cancel?: boolean): void;
+    stopAsync(cancel?: boolean): Promise<boolean>;
+    stopRowAsync(cancel?: boolean): Promise<boolean>;
+    private finishCellStop;
+    private finishRowStop;
+    private commitRowDrafts;
+    private mountRowDraft;
+    private unmountRowDraft;
+    private captureRowDraft;
+    private createCellEditor;
     private validateValue;
+    private validateRowDraft;
+    private showRowErrors;
     private showError;
+    private setCellBusy;
+    private setRowBusy;
     private applyValue;
-    private onEditorKeyDown;
-    private onEditorBlur;
+    private focusEditor;
+    private destroyMountedEditor;
+    private currentRowIndex;
+    private onCellEditorKeyDown;
+    private onRowEditorKeyDown;
+    private onCellEditorBlur;
     destroy(): void;
 }
 
@@ -1107,6 +1411,7 @@ declare class ColumnMenuService {
     private panel;
     private openColId;
     private standaloneAnchor;
+    private searchText;
     constructor(core: ColumnMenuContext);
     toggle(column: Column, anchor: HTMLElement): void;
     openStandalone(anchor?: HTMLElement): void;
@@ -1116,6 +1421,7 @@ declare class ColumnMenuService {
     private docKeyDown;
     private open;
     private rebuildListStates;
+    private renderColumnList;
 }
 
 type ContextMenuContext = Pick<GridCore<any>, "bodyRenderer" | "clearRangeValues" | "columnModel" | "copyActiveRange" | "getApi" | "getCellValue" | "getLocaleText" | "options" | "pasteFromSystemClipboard" | "reportError" | "rowModel">;
@@ -1192,6 +1498,26 @@ declare class UndoRedoService {
     clear(): void;
 }
 
+type ChangeTrackingContext = Pick<GridCore<any>, "bodyRenderer" | "columnModel" | "emit" | "eventBus" | "getCellValue" | "rowModel" | "statusBarService" | "summaryRenderer" | "writeValue">;
+declare class ChangeTrackingService<TData = any> {
+    private core;
+    private changes;
+    private rollingBack;
+    private unsubscribe;
+    constructor(core: ChangeTrackingContext);
+    init(): void;
+    private record;
+    getDirtyRowIds(): string[];
+    getChanges(): GridChange<TData>[];
+    markSaved(rowIds?: readonly string[]): void;
+    acknowledge(saved: readonly GridChange<TData>[]): void;
+    rollback(rowIds?: readonly string[]): boolean;
+    clearRows(rowIds: readonly string[]): void;
+    clear(): void;
+    destroy(): void;
+    private emitChanged;
+}
+
 type SkeletonContext = Pick<GridCore<any>, "options" | "relayout" | "reportError">;
 declare class GridSkeleton {
     private core;
@@ -1213,12 +1539,15 @@ declare class GridSkeleton {
     private currentOverlay;
     private currentOverlayContent;
     private currentOverlayAllowsHtml;
+    private overlayCleanup;
     private customClassTokens;
     private resizeObserver;
     private headerDepth;
     constructor(core: SkeletonContext);
     init(container: HTMLElement, options: ResolvedGridOptions): void;
+    applyAriaLabels(options: Pick<ResolvedGridOptions, "ariaLabel" | "ariaLabelledBy" | "ariaDescribedBy">): void;
     setHeaderRowCount(depth: number): void;
+    getHeaderRowCount(): number;
     private applyHeaderHeight;
     setPaneWidths(left: number, right: number): void;
     private applyPaneWidth;
@@ -1235,6 +1564,7 @@ declare class GridSkeleton {
     hideOverlay(): void;
     setInfiniteLoading(active: boolean, text: string): void;
     destroy(): void;
+    private cleanupOverlayContent;
 }
 
 type HeaderContext = Pick<GridCore<any>, "columnDragService" | "columnMenu" | "columnModel" | "cycleSort" | "emit" | "filterPopup" | "getApi" | "isDestroyed" | "moveColumn" | "options" | "relayoutColumns" | "reportError" | "resizeService" | "rowModel" | "selectionService" | "skeleton">;
@@ -1250,6 +1580,7 @@ declare class HeaderRenderer {
     applyLayout(): void;
     private visiblePaneLeaves;
     private onHeaderKeyDown;
+    private focusHeaderCell;
     refreshSortIndicators(): void;
     refreshFilterIcons(): void;
     refreshSelectAllCheckbox(): void;
@@ -1305,6 +1636,9 @@ declare class BodyRenderer {
     flushFlash(): void;
     relayout(): void;
     private growPool;
+    private activePaneColumns;
+    private createCell;
+    private reconcilePaneCells;
     rebuildPool(): void;
     applyCellLayout(): void;
     private computeColWindow;
@@ -1317,6 +1651,8 @@ declare class BodyRenderer {
     private renderDetailContent;
     private cleanupDetail;
     private renderCell;
+    private appendEditableIndicator;
+    private releaseSlotEditors;
     private treeColumnCache;
     private getTreeColumn;
     private renderTreeCell;
@@ -1372,6 +1708,7 @@ declare class BodyRenderer {
     focusGridRoot(): void;
     private resolveEventTarget;
     private onBodyClick;
+    private handleTreeToggleClick;
     private firstCheckboxColId;
     private onBodyDblClick;
     private onContextMenu;
@@ -1465,6 +1802,7 @@ declare class GridCore<TData = any> {
     readonly keyboardService: KeyboardService;
     readonly editingService: EditingService;
     readonly undoService: UndoRedoService;
+    readonly changeTracker: ChangeTrackingService<TData>;
     readonly filterPopup: FilterPopupService;
     readonly columnMenu: ColumnMenuService;
     readonly contextMenuService: ContextMenuService;
@@ -1478,10 +1816,16 @@ declare class GridCore<TData = any> {
     private destroyed;
     private autoIdCounter;
     private readyRafId;
+    private readySettled;
+    private readonly readyPromise;
+    private readonly resolveReady;
     private lastColumnLayoutSignature;
     private activeFeatures;
+    private recentErrors;
     constructor(container: HTMLElement, options: GridOptions<TData>);
     getApi(): GridApi<TData>;
+    whenReady(): Promise<GridApi<TData>>;
+    private settleReady;
     resolveCellRenderer(name: string): CellRendererFn | undefined;
     resolveCellEditor(name: string): CellEditorFactory | undefined;
     setFeatures(features: readonly GridFeature<TData>[] | null | undefined): void;
@@ -1492,6 +1836,8 @@ declare class GridCore<TData = any> {
     getLocaleText(key: RgLocaleKey): string;
     writeValue(node: RowNode<any>, column: Column, newValue: any, oldValue?: any): boolean;
     setCellValue(node: RowNode<any>, column: Column, newValue: any, oldValue: any): boolean;
+    /** Emits the shared value-change side effects after a caller has written data transactionally. */
+    notifyCellValueChanged(node: RowNode<any>, column: Column, oldValue: any, newValue: any): void;
     buildRangeTsv(range: {
         r1: number;
         c1: number;
@@ -1510,6 +1856,8 @@ declare class GridCore<TData = any> {
     refreshSummary(): void;
     emit<K extends GridEventType>(type: K, extra?: Partial<GridEventMap<TData>[K]>): GridEventMap<TData>[K];
     reportError(error: unknown, source: string, context?: Record<string, unknown>): void;
+    private errorCodeFor;
+    getDiagnostics(): GridDiagnostics;
     cycleSort(column: Column, additive: boolean): void;
     applySortModel(): void;
     applyColumnFilter(column: Column, filter: ColumnFilter | null): void;
@@ -1522,10 +1870,11 @@ declare class GridCore<TData = any> {
     buildDefaultEmptyState(): HTMLElement;
     private lastValidatedDefs;
     private issuedWarningSignatures;
-    checkWarnings(): void;
+    checkWarnings(inputOptions?: Partial<GridOptions<any>> | Record<string, unknown>): void;
     validateDefs(defs: (ColDef<any> | ColDefGroup<any>)[] | null | undefined): void;
     onColumnsStructureChanged(): void;
     relayout(): void;
+    refreshAriaState(): void;
     relayoutColumns(invalidateRowHeights?: boolean): void;
     destroy(): void;
 }
@@ -1543,6 +1892,8 @@ interface WidthInput {
     flex?: number;
 }
 declare function computeColumnWidths(cols: WidthInput[], availableWidth: number): number[];
+/** Fits columns into a viewport while honoring every min/max bound. */
+declare function fitColumnWidths(cols: WidthInput[], availableWidth: number): number[];
 
 interface GridSizePreset {
     rowHeight: number;
@@ -1581,6 +1932,10 @@ declare const GRID_OPTION_META: {
         readonly kind: "object";
         readonly update: "options";
     };
+    readonly columnTypes: {
+        readonly kind: "object";
+        readonly update: "options";
+    };
     readonly getRowId: {
         readonly kind: "function";
         readonly update: "options";
@@ -1597,6 +1952,10 @@ declare const GRID_OPTION_META: {
         readonly kind: "number";
         readonly update: "options";
     };
+    readonly columnLayout: {
+        readonly kind: "string";
+        readonly update: "options";
+    };
     readonly rowSelection: {
         readonly kind: "string";
         readonly update: "options";
@@ -1665,14 +2024,34 @@ declare const GRID_OPTION_META: {
         readonly kind: "object";
         readonly update: "options";
     };
+    readonly actionPolicy: {
+        readonly kind: "object";
+        readonly update: "options";
+    };
     readonly features: {
         readonly kind: "array";
         readonly update: "options";
     };
+    readonly initialState: {
+        readonly kind: "object";
+        readonly update: "options";
+    };
     readonly locale: {
         readonly kind: "object";
         readonly update: "options";
     };
+    readonly editType: {
+        readonly kind: "string";
+        readonly update: "options";
+    };
+    readonly editableIndicator: {
+        readonly kind: "string";
+        readonly update: "options";
+    };
+    readonly rowEditValidator: {
+        readonly kind: "function";
+        readonly update: "options";
+    };
     readonly singleClickEdit: {
         readonly kind: "boolean";
         readonly update: "options";
@@ -1701,6 +2080,14 @@ declare const GRID_OPTION_META: {
         readonly kind: "string";
         readonly update: "options";
     };
+    readonly isTreeRowExpandable: {
+        readonly kind: "function";
+        readonly update: "options";
+    };
+    readonly loadTreeChildren: {
+        readonly kind: "function";
+        readonly update: "options";
+    };
     readonly autoCheckedChildren: {
         readonly kind: "boolean";
         readonly update: "options";
@@ -1721,6 +2108,10 @@ declare const GRID_OPTION_META: {
         readonly kind: "number";
         readonly update: "options";
     };
+    readonly asyncTransactionWaitMillis: {
+        readonly kind: "number";
+        readonly update: "options";
+    };
     readonly getRowHeight: {
         readonly kind: "function";
         readonly update: "options";
@@ -1793,6 +2184,14 @@ declare const GRID_OPTION_META: {
         readonly kind: "number";
         readonly update: "options";
     };
+    readonly datasourceRetryCount: {
+        readonly kind: "number";
+        readonly update: "options";
+    };
+    readonly datasourceRetryDelay: {
+        readonly kind: "number";
+        readonly update: "options";
+    };
     readonly suppressCellFocus: {
         readonly kind: "boolean";
         readonly update: "options";
@@ -1809,6 +2208,18 @@ declare const GRID_OPTION_META: {
         readonly kind: "boolean";
         readonly update: "options";
     };
+    readonly ariaLabel: {
+        readonly kind: "string";
+        readonly update: "options";
+    };
+    readonly ariaLabelledBy: {
+        readonly kind: "string";
+        readonly update: "options";
+    };
+    readonly ariaDescribedBy: {
+        readonly kind: "string";
+        readonly update: "options";
+    };
     readonly loading: {
         readonly kind: "boolean";
         readonly update: "options";
@@ -1835,6 +2246,16 @@ declare const DIRECT_GRID_OPTION_KEYS: readonly GridOptionKey[];
 
 declare function describeFilter(filter: ColumnFilter): string;
 
+type GridValidationCode = "UNKNOWN_OPTION" | "INVALID_OPTION_VALUE" | "OPTION_CONFLICT" | "MISSING_STABLE_ROW_ID";
+interface GridValidationIssue {
+    code: GridValidationCode;
+    message: string;
+    option?: string;
+    suggestion?: string;
+}
+/** Runtime validation for JavaScript, JSON/schema driven and dynamic options. */
+declare function validateGridOptions(options: Partial<GridOptions<any>> | Record<string, unknown>): GridValidationIssue[];
+
 type GridSchemaFieldType = "string" | "number" | "date" | "select" | "boolean";
 interface SchemaSelectOption {
     label: string;
@@ -1868,6 +2289,45 @@ interface GridSchema {
 }
 declare function buildColDefsFromSchema<TData = any>(schema: GridSchema): (ColDef<TData> | ColDefGroup<TData>)[];
 
+interface ColumnStateStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface StoredColumnState {
+    version: number;
+    savedAt: number;
+    columns: ColumnState[];
+}
+interface LocalColumnStateStoreOptions {
+    /** Storage prefix. Separate applications or environments with different values. */
+    namespace?: string;
+    /** Schema version for migrations when column identifiers or meanings change. */
+    version?: number;
+    storage?: ColumnStateStorage;
+    maxColumns?: number;
+    migrate?(columns: readonly ColumnState[], fromVersion: number, toVersion: number): ColumnState[] | null;
+    onError?(error: unknown, operation: "load" | "save" | "clear", key: string): void;
+}
+interface ManagedColumnStateStore extends ColumnStateStore {
+    clear(key: string): void;
+    storageKey(key: string): string;
+}
+interface ColumnStateKeyParts {
+    app?: string;
+    tenant?: string | number;
+    user?: string | number;
+    route?: string;
+    table: string;
+    schema?: string | number;
+}
+/** Builds a collision-resistant key for per-user/per-route table preferences. */
+declare function createColumnStateKey(parts: ColumnStateKeyParts): string;
+/**
+ * Creates a versioned local state adapter. Legacy array payloads are read as
+ * version 0, so existing users can migrate without losing preferences.
+ */
+declare function createLocalColumnStateStore(options?: LocalColumnStateStoreOptions): ManagedColumnStateStore;
 declare function saveColumnState(key: string, state: ColumnState[]): void;
 declare function loadColumnState(key: string): ColumnState[] | null;
 declare function clearColumnState(key: string): void;
@@ -1907,28 +2367,141 @@ interface ProgressConfig {
 }
 declare function createProgressBarRenderer(config?: ProgressConfig): CellRendererFn;
 declare function linkRenderer(params: CellRendererParams): string | HTMLElement;
+type ActionVariant = "default" | "primary" | "warning" | "success" | "danger";
+type ActionOverflowMode = "menu" | "drawer" | "inline";
 interface ActionItem<TData = any> {
+    /** Stable identifier used by permission, telemetry and error policies. */
+    id?: string;
     icon?: string;
     label?: string;
     title?: string;
+    /** Backwards-compatible shorthand for variant="danger". */
     danger?: boolean;
+    variant?: ActionVariant;
     show?: (params: CellRendererParams<TData>) => boolean;
-    onClick: (params: CellRendererParams<TData>) => void;
-}
-interface ActionButtonsConfig {
-    actions: ActionItem[];
+    disabled?: boolean | ((params: CellRendererParams<TData>) => boolean);
+    loading?: boolean | ((params: CellRendererParams<TData>) => boolean);
+    /** One or more UI permissions. Access is resolved by GridOptions.actionPolicy. */
+    permission?: string | readonly string[];
+    /** Ask for confirmation before running. A string becomes the confirmation message. */
+    confirm?: boolean | string | ((params: CellRendererParams<TData>) => boolean | string | Promise<boolean | string>);
+    onClick: (params: CellRendererParams<TData>) => unknown | Promise<unknown>;
+}
+interface ActionButtonsConfig<TData = any> {
+    actions: ActionItem<TData>[];
     max?: number;
-}
-declare function createActionButtonsRenderer(config: ActionButtonsConfig): CellRendererFn;
+    /** menu is compact, drawer suits touch/complex actions, inline never renders an ellipsis. */
+    overflow?: ActionOverflowMode;
+    moreLabel?: string;
+    drawerTitle?: string;
+}
+interface RowActionsConfig<TData = any> extends Omit<ActionButtonsConfig<TData>, "actions"> {
+    onView?: (params: CellRendererParams<TData>) => unknown | Promise<unknown>;
+    onDelete?: (params: CellRendererParams<TData>) => unknown | Promise<unknown>;
+    /** Set false when this table has no full-row edit workflow. */
+    edit?: boolean;
+    extraActions?: ActionItem<TData>[];
+    labels?: Partial<Record<"view" | "edit" | "delete" | "save" | "cancel", string>>;
+    permissions?: Partial<Record<"view" | "edit" | "delete", string | readonly string[]>>;
+    /** Defaults to the translated delete label when true. */
+    confirmDelete?: boolean | string | ((params: CellRendererParams<TData>) => boolean | string | Promise<boolean | string>);
+}
+declare function createActionButtonsRenderer<TData = any>(config: ActionButtonsConfig<TData>): CellRendererFn;
+declare function createRowActionsRenderer<TData = any>(config?: RowActionsConfig<TData>): CellRendererFn;
 declare function registerBuiltinRenderers(register: (name: string, fn: CellRendererFn) => void): void;
 
 declare function selectionColumn<TData = any>(overrides?: Partial<ColDef<TData>>): ColDef<TData>;
 declare function indexColumn<TData = any>(overrides?: Partial<ColDef<TData>>): ColDef<TData>;
 declare function dragColumn<TData = any>(overrides?: Partial<ColDef<TData>>): ColDef<TData>;
-declare function actionsColumn<TData = any>(config?: ActionButtonsConfig & {
+declare function actionsColumn<TData = any>(config?: ActionButtonsConfig<TData> & {
     width?: number;
     pinned?: "left" | "right";
 }): ColDef<TData>;
+declare function rowActionsColumn<TData = any>(config?: RowActionsConfig<TData> & {
+    width?: number;
+    pinned?: "left" | "right";
+}): ColDef<TData>;
+
+type Callable = (...args: never[]) => unknown;
+type Primitive = string | number | boolean | bigint | symbol | null | undefined | Date | Callable;
+type Depth = 0 | 1 | 2 | 3 | 4;
+type Previous = {
+    0: 0;
+    1: 0;
+    2: 1;
+    3: 2;
+    4: 3;
+};
+type FieldPath<T, D extends Depth = 4> = D extends 0 ? never : T extends Primitive ? never : {
+    [K in keyof T & string]: NonNullable<T[K]> extends Primitive | readonly unknown[] ? K : K | `${K}.${FieldPath<NonNullable<T[K]>, Previous[D]>}`;
+}[keyof T & string];
+type FieldPathValue<T, P extends string> = P extends keyof T ? T[P] : P extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? FieldPathValue<NonNullable<T[Head]>, Tail> : unknown : unknown;
+interface ColumnHelper<TData> {
+    accessor<TPath extends FieldPath<TData>>(field: TPath, definition?: Omit<ColDef<TData, FieldPathValue<TData, TPath>>, "field">): ColDef<TData, FieldPathValue<TData, TPath>>;
+    display<TValue = unknown>(definition: Omit<ColDef<TData, TValue>, "field"> & Required<Pick<ColDef<TData, TValue>, "colId">>): ColDef<TData, TValue>;
+    group(definition: ColDefGroup<TData>): ColDefGroup<TData>;
+}
+/** Creates strongly typed column definitions without repeating TData/TValue. */
+declare function createColumnHelper<TData>(): ColumnHelper<TData>;
+/** Identity helper that retains literal types while checking GridOptions elsewhere. */
+declare function defineColumns<TData>(columns: readonly (ColDef<TData> | ColDefGroup<TData>)[]): (ColDef<TData> | ColDefGroup<TData>)[];
+
+/** Merges reusable defaults left-to-right with nested defaults handled safely. */
+declare function createMachTablePreset<TData>(...sources: readonly Partial<GridOptions<TData>>[]): GridOptions<TData>;
+/** Recommended defaults for editable enterprise back-office screens. */
+declare function createEnterprisePreset<TData>(overrides?: Partial<GridOptions<TData>>): GridOptions<TData>;
+/** Compile-time helper for a reusable partial preset. */
+declare function defineMachTablePreset<TData>(preset: Partial<GridOptions<TData>>): Partial<GridOptions<TData>>;
+/** Compile-time helper for reusable, typed grid option objects. */
+declare function defineGridOptions<TData>(options: GridOptions<TData>): GridOptions<TData>;
+
+type BusinessColumnType = "text" | "number" | "integer" | "money" | "percent" | "percentage" | "date" | "datetime" | "boolean" | "status" | "link";
+interface BusinessColumnTypeOptions {
+    locale?: string | readonly string[];
+    currency?: string;
+    currencyDisplay?: "symbol" | "narrowSymbol" | "code" | "name";
+    timeZone?: string;
+    emptyText?: string;
+    invalidText?: string;
+    trueText?: string;
+    falseText?: string;
+    maximumFractionDigits?: number;
+}
+/**
+ * Production-oriented semantic column types. Register once in
+ * `mach-table.config.ts`, then pages only declare `type: "money"` etc.
+ */
+declare function createBusinessColumnTypes<TData = any>(options?: BusinessColumnTypeOptions): Readonly<Record<BusinessColumnType, Partial<ColDef<TData>>>>;
+type DictionaryKey = string | number;
+interface DictionaryEntry<TKey extends DictionaryKey = DictionaryKey> {
+    value: TKey;
+    label: string;
+}
+interface CachedDictionaryOptions<TKey extends DictionaryKey = DictionaryKey> {
+    load(keys: readonly TKey[], signal: AbortSignal): Promise<readonly DictionaryEntry<TKey>[]>;
+    ttlMs?: number;
+    maxSize?: number;
+    batchDelayMs?: number;
+    onError?(error: unknown, keys: readonly TKey[]): void;
+}
+interface CachedDictionary<TKey extends DictionaryKey = DictionaryKey> {
+    get(key: TKey): string | undefined;
+    resolve(key: TKey): Promise<string | undefined>;
+    resolveMany(keys: readonly TKey[]): Promise<ReadonlyMap<TKey, string>>;
+    prime(entries: readonly DictionaryEntry<TKey>[]): void;
+    invalidate(keys?: readonly TKey[]): void;
+    destroy(): void;
+    readonly size: number;
+}
+/** Batched, de-duplicated TTL/LRU dictionary resolver for code-to-label fields. */
+declare function createCachedDictionary<TKey extends DictionaryKey = DictionaryKey>(options: CachedDictionaryOptions<TKey>): CachedDictionary<TKey>;
+interface DictionaryRendererOptions {
+    loadingText?: string;
+    emptyText?: string;
+    fallback?: (value: DictionaryKey) => string;
+}
+/** Async-safe renderer backed by createCachedDictionary; stale pooled cells are not mutated. */
+declare function createDictionaryRenderer<TKey extends DictionaryKey = DictionaryKey>(dictionary: CachedDictionary<TKey>, options?: DictionaryRendererOptions): CellRendererFn;
 
 declare function evaluateColumnFilter(value: any, filter: ColumnFilter): boolean;
 
@@ -1936,4 +2509,4 @@ declare function sortNodes<TData>(nodes: RowNode<TData>[], sortModel: SortModel,
 
 declare const version: string;
 
-export { type ActionButtonsConfig, type ActionItem, type AggFunction, type AggValues, BUILTIN_AGG_FUNCS, type CellAlign, type CellClassParams, type CellClassRule, type CellClickEvent, type CellContextMenuEvent, type CellDoubleClickEvent, type CellEditingStartedEvent, type CellEditingStoppedEvent, type CellEditorFactory, type CellEditorParams, type CellRendererFn, type CellRendererOutput, type CellRendererParams, type CellStyleRule, type CellValueChangedEvent, type ColDef, type ColDefGroup, type ColDefOrGroup, Column, type ColumnFilter, type ColumnMovedEvent, type ColumnResizedEvent, type ColumnState, type ColumnStateStore, type ColumnVisibilityChangedEvent, type ContextMenuItem, type ContextMenuParams, type CsvExportParams, DEFAULT_LOCALE, DIRECT_GRID_OPTION_KEYS, type DateFilterCondition, type DateFilterMatch, type DetailRowRendererParams, type DetailToggledEvent, EVENT_TYPES, type EditableParams, EventBus, type EventHandlers, type FilterChangedEvent, type FilterModel, type FilterType, GRID_OPTION_KEYS, GRID_OPTION_META, GRID_SIZE_PRESETS, type GetRowHeightParams, type GetRowIdParams, type GridApi, type GridCellRange, type GridComponents, GridCore, type GridDatasource, type GridErrorEvent, type GridEventBase, type GridEventMap, type GridEventType, type GridFeature, type GridFeatureContext, type GridOptionKey, type GridOptionMetadata, type GridOptionUpdateMode, type GridOptionValueKind, type GridOptions, type GridReadyEvent, type GridSchema, type GridSchemaField, type GridSchemaFieldType, type GridSchemaGroup, type GridSize, type GridSizePreset, type HeaderComponentParams, type ICellEditor, type ICellRendererResult, type ImportCsvOptions, type InfiniteGetRowsParams, LOCALE_EN, type ModelUpdatedEvent, type NumberFilterCondition, type NumberFilterMatch, type OverlayTemplate, type PaginationChangedEvent, type PaginationConfig, type PinnedDirection, type PrintOptions, type ProgressConfig, type RangeSelectionChangedEvent, type ResolvedGridOptions, type RgLocale, type RgLocaleKey, type RowClickEvent, type RowDragEndEvent, type RowNode, type RowSelectionMode, type RowTransaction, type SchemaSelectOption, type SelectEditorParams, type SelectionChangedEvent, type SetFilterCondition, type SetFilterParams, type SortChangedEvent, type SortDirection, type SortModel, type SortModelItem, type StatusBarConfig, type StatusBarPanel, type StatusTagConfig, type TagVariant, type TextFilterCondition, type TextFilterMatch, type ThemeMode, type TooltipParams, type ValueFormatterParams, type ValueGetterParams, type ValueSetterParams, type WatermarkConfig, type WidthInput, actionsColumn, buildColDefsFromSchema, clearColumnState, clearComponentRegistries, computeColumnWidths, createActionButtonsRenderer, createAggResolver, createGrid, createProgressBarRenderer, createStatusTagRenderer, defaultComparator, describeFilter, downloadFile, dragColumn, escapeHtml, evaluateColumnFilter, formatText, formatTwo, getByPath, getCellEditor, getCellRenderer, indexColumn, isColDefGroup, isSafePath, linkRenderer, loadColumnState, matchLocaleKey, parseCsv, parseDelimited, parseTsv, registerBuiltinRenderers, registerCellEditor, registerCellRenderer, resolveTagVariant, sanitizeFormulaCell, saveColumnState, selectionColumn, setByPath, sortNodes, toTsv, version };
+export { type ActionButtonsConfig, type ActionItem, type ActionOverflowMode, type ActionPolicy, type ActionPolicyContext, type ActionVariant, type AggFunction, type AggValues, type ApplyGridStateOptions, BUILTIN_AGG_FUNCS, type BusinessColumnType, type BusinessColumnTypeOptions, type CachedDictionary, type CachedDictionaryOptions, type CellAlign, type CellClassParams, type CellClassRule, type CellClickEvent, type CellContextMenuEvent, type CellDoubleClickEvent, type CellEditingStartedEvent, type CellEditingStoppedEvent, type CellEditorFactory, type CellEditorParams, type CellRendererFn, type CellRendererOutput, type CellRendererParams, type CellStyleRule, type CellValueChangedEvent, type ColDef, type ColDefGroup, type ColDefOrGroup, Column, type ColumnFilter, type ColumnHelper, type ColumnLayoutMode, type ColumnMovedEvent, type ColumnResizedEvent, type ColumnState, type ColumnStateKeyParts, type ColumnStateStorage, type ColumnStateStore, type ColumnVisibilityChangedEvent, type ColumnWorkbenchItem, type ContextMenuItem, type ContextMenuParams, type CsvExportParams, DEFAULT_LOCALE, DIRECT_GRID_OPTION_KEYS, type DateFilterCondition, type DateFilterMatch, type DetailRowRendererParams, type DetailToggledEvent, type DictionaryEntry, type DictionaryKey, type DictionaryRendererOptions, type DirtyStateChangedEvent, EVENT_TYPES, type EditableIndicator, type EditableParams, EventBus, type EventHandlers, type FieldPath, type FieldPathValue, type FilterChangedEvent, type FilterModel, type FilterType, GRID_OPTION_KEYS, GRID_OPTION_META, GRID_SIZE_PRESETS, type GetRowHeightParams, type GetRowIdParams, type GridApi, type GridCellChange, type GridCellRange, type GridChange, type GridComponents, GridCore, type GridDatasource, type GridDiagnosticError, type GridDiagnostics, type GridEditType, type GridErrorCode, type GridErrorEvent, type GridEventBase, type GridEventMap, type GridEventType, type GridFeature, type GridFeatureContext, type GridOptionKey, type GridOptionMetadata, type GridOptionUpdateMode, type GridOptionValueKind, type GridOptions, type GridReadyEvent, type GridSchema, type GridSchemaField, type GridSchemaFieldType, type GridSchemaGroup, type GridSize, type GridSizePreset, type GridState, type GridStateSection, type GridValidationCode, type GridValidationIssue, type HeaderComponentParams, type ICellEditor, type ICellRendererResult, type ImportCsvOptions, type InfiniteGetRowsParams, LOCALE_EN, type LocalColumnStateStoreOptions, type ManagedColumnStateStore, type ModelUpdatedEvent, type NumberFilterCondition, type NumberFilterMatch, type OverlayContent, type OverlayTemplate, type PaginationChangedEvent, type PaginationConfig, type PinnedDirection, type PrintOptions, type ProgressConfig, type RangeSelectionChangedEvent, type ResolvedGridOptions, type RgLocale, type RgLocaleKey, type RowActionsConfig, type RowClickEvent, type RowDragEndEvent, type RowEditChange, type RowEditValidationParams, type RowEditValidationResult, type RowEditingStartedEvent, type RowEditingStoppedEvent, type RowNode, type RowSelectionMode, type RowTransaction, type SaveChangesHandler, type SaveChangesResult, type SchemaSelectOption, type SelectEditorParams, type SelectionChangedEvent, type SetFilterCondition, type SetFilterParams, type SortChangedEvent, type SortDirection, type SortModel, type SortModelItem, type StatusBarConfig, type StatusBarPanel, type StatusTagConfig, type StoredColumnState, type TagVariant, type TextFilterCondition, type TextFilterMatch, type ThemeMode, type TooltipParams, type TreeChildrenLoadFailedEvent, type TreeChildrenLoadedEvent, type TreeDataLoadParams, type ValueFormatterParams, type ValueGetterParams, type ValueSetterParams, type WatermarkConfig, type WidthInput, actionsColumn, buildColDefsFromSchema, clearColumnState, clearComponentRegistries, computeColumnWidths, createActionButtonsRenderer, createAggResolver, createBusinessColumnTypes, createCachedDictionary, createColumnHelper, createColumnStateKey, createDictionaryRenderer, createEnterprisePreset, createGrid, createLocalColumnStateStore, createMachTablePreset, createProgressBarRenderer, createRowActionsRenderer, createStatusTagRenderer, defaultComparator, defineColumns, defineGridOptions, defineMachTablePreset, describeFilter, downloadFile, dragColumn, escapeHtml, evaluateColumnFilter, fitColumnWidths, formatText, formatTwo, getByPath, getCellEditor, getCellRenderer, indexColumn, isColDefGroup, isSafePath, linkRenderer, loadColumnState, matchLocaleKey, parseCsv, parseDelimited, parseTsv, registerBuiltinRenderers, registerCellEditor, registerCellRenderer, resolveTagVariant, rowActionsColumn, sanitizeFormulaCell, saveColumnState, selectionColumn, setByPath, sortNodes, toTsv, validateGridOptions, version };