@agile-team/mach-table 0.14.0 → 0.18.0

package/dist/index.d.cts

@@ -14,6 +14,7 @@ declare class Column<TData = any> {
     hide: boolean;
     pinned: PinnedDirection | null;
     manualWidth: number | null;
+    flex: number | null;
     currentWidth: number;
     parentGroup: ColumnGroup<TData> | null;
     level: number;
@@ -25,6 +26,7 @@ declare class Column<TData = any> {
     get filterable(): boolean;
     get filterType(): FilterType;
     get hasCheckbox(): boolean;
+    resetWidth(): void;
 }
 
 interface RowNode<TData = any> {
@@ -45,6 +47,25 @@ interface RowNode<TData = any> {
     treeLoadError?: unknown;
 }
 
+interface AdvancedFilterCondition {
+    kind: "condition";
+    colId: string;
+    filter: ColumnFilter;
+}
+interface AdvancedFilterGroup {
+    kind: "group";
+    operator: "and" | "or";
+    children: AdvancedFilterNode[];
+    /** Negates the complete group without changing its children. */
+    not?: boolean;
+}
+type AdvancedFilterNode = AdvancedFilterCondition | AdvancedFilterGroup;
+/** Serializable, backend-friendly nested filter expression. */
+interface AdvancedFilterModel {
+    version: 1;
+    root: AdvancedFilterNode;
+}
+
 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];
 type GridErrorCode = "DATA_SOURCE_ERROR" | "DATA_INTEGRITY_ERROR" | "VALIDATION_ERROR" | "RENDERER_ERROR" | "EDITOR_ERROR" | "FEATURE_ERROR" | "STATE_ERROR" | "EVENT_HANDLER_ERROR" | "GRID_ERROR";
@@ -107,6 +128,7 @@ interface SortChangedEvent<TData = any> extends GridEventBase<TData> {
 interface FilterChangedEvent<TData = any> extends GridEventBase<TData> {
     type: "filterChanged";
     filterModel: FilterModel;
+    advancedFilterModel: AdvancedFilterModel | null;
 }
 interface ColumnResizedEvent<TData = any> extends GridEventBase<TData> {
     type: "columnResized";
@@ -320,10 +342,7 @@ 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;
+interface GridStateBase {
     columns: ColumnState[];
     sortModel: SortModel;
     filterModel: FilterModel;
@@ -337,6 +356,17 @@ interface GridState {
     expandedRowIds: string[];
     expandedGroupIds: string[];
 }
+/** Read-only compatibility shape accepted from MachTable 0.14/0.15. */
+interface LegacyGridStateV1 extends GridStateBase {
+    version: 1;
+}
+/** Serializable snapshot of user-visible grid state. */
+interface GridState extends GridStateBase {
+    /** State schema version, independent from the package version. */
+    version: 2;
+    advancedFilterModel: AdvancedFilterModel | null;
+}
+type GridStateInput = GridState | LegacyGridStateV1;
 type GridStateSection = "columns" | "sort" | "filter" | "pagination" | "selection" | "expansion";
 interface ApplyGridStateOptions {
     /** Applies all sections when omitted. */
@@ -366,8 +396,8 @@ interface ColumnStateStore {
     save(key: string, state: ColumnState[]): void | Promise<void>;
 }
 interface GridStateStore {
-    load(key: string): GridState | null | Promise<GridState | null>;
-    save(key: string, state: GridState): void | Promise<void>;
+    load(key: string): GridStateInput | null | Promise<GridStateInput | null>;
+    save(key: string, state: GridStateInput): void | Promise<void>;
     clear?(key: string): void | Promise<void>;
 }
 /** Per-grid component overrides. These take precedence over the global registry. */
@@ -390,6 +420,12 @@ interface GridFeatureContext<TData = any> {
 /** Composable extension point; feature instances are scoped to one grid. */
 interface GridFeature<TData = any> {
     readonly key: string;
+    /** Informational extension version exposed through diagnostics. */
+    readonly version?: string;
+    /** Feature keys that must be initialised before this feature. */
+    readonly requires?: readonly string[];
+    /** Mutually exclusive feature keys. Conflicting features are not initialised. */
+    readonly conflicts?: readonly string[];
     setup(context: GridFeatureContext<TData>): void | (() => void);
     destroy?(): void;
 }
@@ -408,6 +444,7 @@ interface InfiniteGetRowsParams<TData = any> {
     endRow: number;
     sortModel: SortModel;
     filterModel: FilterModel;
+    advancedFilterModel: AdvancedFilterModel | null;
     quickFilterText: string | null;
     signal: AbortSignal;
     onSuccess(rows: TData[], lastRow?: number): void;
@@ -496,6 +533,8 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
     rowBuffer?: number;
     /** `fit` continuously fills the container without grid-ready glue code. */
     columnLayout?: ColumnLayoutMode;
+    /** Enables pointer, double-click and Alt+Arrow column resizing. Disabled by default. */
+    enableColumnResize?: boolean;
     /** Lets small grids grow with their rows. Avoid for large or infinite datasets. */
     domLayout?: DomLayoutMode;
     rowSelection?: RowSelectionMode;
@@ -505,6 +544,8 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
     showCellBorders?: boolean;
     theme?: ThemeMode;
     quickFilterText?: string | null;
+    /** Nested AND/OR filter expression, safe for local evaluation and backend serialization. */
+    advancedFilterModel?: AdvancedFilterModel | null;
     masterDetail?: boolean;
     detailRowHeight?: number;
     detailRowRenderer?: (params: DetailRowRendererParams<TData>) => string | HTMLElement | ICellRendererResult | null | undefined;
@@ -519,7 +560,7 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
     actionPolicy?: ActionPolicy<TData>;
     features?: readonly GridFeature<TData>[];
     /** State restored atomically after columns and initial rows are available. */
-    initialState?: GridState;
+    initialState?: GridStateInput;
     /** Persist the complete user-visible GridState with a versioned store. */
     stateKey?: string | null;
     stateStore?: GridStateStore;
@@ -606,6 +647,7 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     headerHeight: number;
     rowBuffer: number;
     columnLayout: ColumnLayoutMode;
+    enableColumnResize: boolean;
     domLayout: DomLayoutMode;
     rowSelection: RowSelectionMode;
     multiSort: boolean;
@@ -614,6 +656,7 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     showCellBorders: boolean;
     theme: ThemeMode;
     quickFilterText: string | null;
+    advancedFilterModel: AdvancedFilterModel | null;
     masterDetail: boolean;
     detailRowHeight: number;
     detailRowRenderer?: (params: DetailRowRendererParams<TData>) => string | HTMLElement | ICellRendererResult | null | undefined;
@@ -626,7 +669,7 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     components?: GridComponents;
     actionPolicy?: ActionPolicy<TData>;
     features: readonly GridFeature<TData>[];
-    initialState?: GridState;
+    initialState?: GridStateInput;
     stateKey: string | null;
     stateStore?: GridStateStore;
     stateSaveDebounceMs: number;
@@ -746,6 +789,17 @@ interface GridDiagnosticError {
     timestamp: number;
     context?: Record<string, unknown>;
 }
+interface GridPerformanceSnapshot {
+    sampleCount: number;
+    lastRenderMs: number;
+    averageRenderMs: number;
+    maxRenderMs: number;
+    p95RenderMs: number;
+    longRenderCount: number;
+    renderedRows: number;
+    renderedColumns: number;
+    renderedCells: number;
+}
 interface ColumnWorkbenchItem {
     colId: string;
     label: string;
@@ -766,13 +820,37 @@ interface GridDiagnostics {
     columnCount: number;
     selectedRowCount: number;
     dirtyRowCount: number;
+    activeFeatures: ReadonlyArray<{
+        key: string;
+        version?: string;
+    }>;
+    performance: GridPerformanceSnapshot;
     recentErrors: readonly GridDiagnosticError[];
 }
-interface SaveChangesResult {
+interface SaveChangeIssue {
+    rowId: string;
+    code?: string;
+    message: string;
+    colIds?: readonly string[];
+    retryable?: boolean;
+}
+interface SaveChangeConflict<TData = any> extends SaveChangeIssue {
+    serverData?: TData;
+    serverVersion?: string | number;
+}
+interface SaveChangesResult<TData = any> {
     /** Omit to acknowledge every submitted row; return a subset for partial batch success. */
     savedRowIds?: readonly string[];
+    failures?: readonly SaveChangeIssue[];
+    conflicts?: readonly SaveChangeConflict<TData>[];
+}
+interface GridBatchSaveResult<TData = any> {
+    submitted: GridChange<TData>[];
+    saved: GridChange<TData>[];
+    failures: SaveChangeIssue[];
+    conflicts: SaveChangeConflict<TData>[];
 }
-type SaveChangesHandler<TData = any> = (changes: readonly GridChange<TData>[]) => void | SaveChangesResult | Promise<void | SaveChangesResult>;
+type SaveChangesHandler<TData = any> = (changes: readonly GridChange<TData>[]) => void | SaveChangesResult<TData> | Promise<void | SaveChangesResult<TData>>;
 interface GridApi<TData = any> {
     /** Resolves after the first layout frame and gridReady emission. */
     whenReady(): Promise<GridApi<TData>>;
@@ -796,6 +874,8 @@ interface GridApi<TData = any> {
     setColumnVisibility(colId: string, visible: boolean): void;
     moveColumn(colId: string, toIndex: number): void;
     setColumnPinned(colId: string, pinned: "left" | "right" | null): void;
+    /** Sets one width without replacing the rest of the column state. */
+    setColumnWidth(colId: string, width: number): boolean;
     sizeColumnsToFit(width?: number): void;
     autoSizeColumn(colId: string, skipHeader?: boolean): void;
     autoSizeAllColumns(skipHeader?: boolean): void;
@@ -803,6 +883,8 @@ interface GridApi<TData = any> {
     setSortModel(sortModel: SortModel | null): void;
     getFilterModel(): FilterModel;
     setFilterModel(filterModel: FilterModel | null): void;
+    getAdvancedFilterModel(): AdvancedFilterModel | null;
+    setAdvancedFilterModel(model: AdvancedFilterModel | null): void;
     isColumnFilterPresent(colId: string): boolean;
     setQuickFilter(text: string | null | undefined): void;
     getQuickFilter(): string | null;
@@ -848,6 +930,7 @@ interface GridApi<TData = any> {
     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>[]>;
+    saveChangesDetailed(handler: SaveChangesHandler<TData>, rowIds?: readonly string[]): Promise<GridBatchSaveResult<TData>>;
     rollbackChanges(rowIds?: readonly string[]): boolean;
     setPinnedTopRowData(rows: TData[] | null): void;
     getPinnedTopRowData(): TData[];
@@ -893,9 +976,12 @@ interface GridApi<TData = any> {
     updateOptions(options: Partial<GridOptions<TData>>): void;
     getDataAsCsv(params?: CsvExportParams): string;
     getState(): GridState;
-    applyState(state: GridState, options?: ApplyGridStateOptions): void;
+    applyState(state: GridStateInput, options?: ApplyGridStateOptions): void;
     /** Lightweight runtime snapshot suitable for support logs and health panels. */
     getDiagnostics(): GridDiagnostics;
+    /** Rolling viewport-render metrics for diagnostics and reproducible benchmarks. */
+    getPerformanceSnapshot(): GridPerformanceSnapshot;
+    resetPerformanceMetrics(): void;
     setOverlay(type: "loading" | "noRows" | "error" | null): void;
     hideOverlays(): void;
     addEventListener<K extends GridEventType>(eventType: K, listener: (event: GridEventMap<TData>[K]) => void): () => void;
@@ -983,6 +1069,8 @@ interface HeaderComponentParams<TData = any> {
 }
 interface ICellRendererResult {
     el: HTMLElement;
+    /** Reuses the mounted renderer for an update. Return false to request recreation. */
+    refresh?(params: CellRendererParams): boolean | void;
     destroy?: () => void;
 }
 type CellRendererOutput = string | HTMLElement | ICellRendererResult | null | undefined;
@@ -1120,6 +1208,10 @@ interface ColumnState {
     colId: string;
     hide?: boolean;
     width?: number;
+    /** Active flex weight. A resize clears flex and turns width into a manual override. */
+    flex?: number | null;
+    /** Distinguishes responsive/definition width from an explicit user or API override. */
+    widthMode?: "auto" | "manual";
     pinned?: "left" | "right" | null;
     sort?: SortDirection | null;
     sortIndex?: number | null;
@@ -1173,12 +1265,14 @@ declare class ColumnModel {
     paneOf(column: Column): PaneType;
     computeLayout(viewportWidth: number): void;
     private widthInputOf;
-    setColumnWidth(column: Column, width: number): void;
+    setColumnWidth(column: Column, width: number): boolean;
     setColumnVisibility(colId: string, visible: boolean): void;
     moveColumn(colId: string, toIndex: number): boolean;
     setColumnPinned(colId: string, pinned: PinnedDirection | null): void;
     getColumnState(): ColumnState[];
     applyColumnState(states: ColumnState[]): void;
+    private applyColumnViewState;
+    private sortModelFromState;
     private applyStateOrder;
     resetColumnState(): void;
     getSortModel(): SortModel;
@@ -1195,6 +1289,7 @@ declare class RowModel<TData = any> {
     private displayed;
     private nodesById;
     private filterModel;
+    private advancedFilterModel;
     private quickFilter;
     private expandedIds;
     private groupExpandedIds;
@@ -1243,6 +1338,8 @@ declare class RowModel<TData = any> {
     private reindexAll;
     setFilterModel(filterModel: FilterModel | null): boolean;
     getFilterModel(): FilterModel;
+    setAdvancedFilterModel(model: AdvancedFilterModel | null | undefined): boolean;
+    getAdvancedFilterModel(): AdvancedFilterModel | null;
     setQuickFilter(text: string | null | undefined): boolean;
     getQuickFilter(): string | null;
     isFilterPresent(): boolean;
@@ -1335,16 +1432,25 @@ declare class SelectionService {
     private recomputeTriState;
 }
 
-type ResizeContext = Pick<GridCore<any>, "columnModel" | "emit" | "persistColumnState" | "relayoutColumns" | "skeleton">;
+type ResizeContext = Pick<GridCore<any>, "columnModel" | "commitColumnWidths" | "emitColumnResize" | "options" | "relayoutColumns" | "skeleton">;
 declare class ResizeService {
     private core;
     private active;
     private rafId;
     private pendingWidth;
     constructor(core: ResizeContext);
-    startResize(e: PointerEvent, column: Column): void;
+    startResize(event: PointerEvent, column: Column): void;
+    cancelResize(restore?: boolean): void;
     private onMove;
     private onUp;
+    private onCancel;
+    private onLostPointerCapture;
+    private finishResize;
+    private applyPendingWidth;
+    private widthFromPointer;
+    private matchActivePointer;
+    private clearFrame;
+    private removeListeners;
     destroy(): void;
 }
 
@@ -1569,6 +1675,14 @@ declare class ChangeTrackingService<TData = any> {
     private emitChanged;
 }
 
+declare class PerformanceMonitor {
+    private samples;
+    start(): number;
+    recordRender(startedAt: number, rows: number, columns: number): void;
+    snapshot(): GridPerformanceSnapshot;
+    reset(): void;
+}
+
 type SkeletonContext = Pick<GridCore<any>, "options" | "relayout" | "reportError">;
 declare class GridSkeleton {
     private core;
@@ -1620,7 +1734,7 @@ declare class GridSkeleton {
     private cleanupOverlayContent;
 }
 
-type HeaderContext = Pick<GridCore<any>, "columnDragService" | "columnMenu" | "columnModel" | "cycleSort" | "emit" | "filterPopup" | "getApi" | "isDestroyed" | "moveColumn" | "options" | "relayoutColumns" | "reportError" | "resizeService" | "rowModel" | "selectionService" | "skeleton">;
+type HeaderContext = Pick<GridCore<any>, "columnDragService" | "columnMenu" | "columnModel" | "commitColumnWidths" | "cycleSort" | "emit" | "filterPopup" | "getApi" | "isDestroyed" | "moveColumn" | "options" | "relayoutColumns" | "reportError" | "resizeService" | "rowModel" | "selectionService" | "skeleton">;
 declare class HeaderRenderer {
     private core;
     private leafCells;
@@ -1634,6 +1748,7 @@ declare class HeaderRenderer {
     private visiblePaneLeaves;
     private onHeaderKeyDown;
     private focusHeaderCell;
+    private canResizeColumn;
     refreshSortIndicators(): void;
     refreshFilterIcons(): void;
     refreshSelectAllCheckbox(): void;
@@ -1647,7 +1762,7 @@ interface NormalizedRange {
     c2: number;
 }
 
-type BodyContext = Pick<GridCore<any>, "buildDefaultEmptyState" | "buildDefaultErrorState" | "columnModel" | "contextMenuService" | "editingService" | "emit" | "getApi" | "getCellValue" | "gridId" | "isDestroyed" | "options" | "pinnedRowsRenderer" | "reportError" | "resolveCellRenderer" | "rowModel" | "selectionService" | "setCellValue" | "skeleton" | "summaryRenderer" | "toggleDetail" | "tooltipService" | "undoService">;
+type BodyContext = Pick<GridCore<any>, "buildDefaultEmptyState" | "buildDefaultErrorState" | "columnModel" | "contextMenuService" | "editingService" | "emit" | "getApi" | "getCellValue" | "gridId" | "isDestroyed" | "options" | "performanceMonitor" | "pinnedRowsRenderer" | "reportError" | "resolveCellRenderer" | "rowModel" | "selectionService" | "setCellValue" | "skeleton" | "summaryRenderer" | "toggleDetail" | "tooltipService" | "undoService">;
 interface FocusedCell {
     rowIndex: number;
     colId: string;
@@ -1697,6 +1812,10 @@ declare class BodyRenderer {
     applyCellLayout(): void;
     private computeColWindow;
     updateRange(force?: boolean): void;
+    private updateRangeInner;
+    private calculateVisibleRange;
+    private hideOutsideRange;
+    private renderVirtualRange;
     private reconcileColumnWindow;
     private renderAutoHeightRange;
     private hideSlot;
@@ -1707,6 +1826,8 @@ declare class BodyRenderer {
     private renderDetailContent;
     private cleanupDetail;
     private renderCell;
+    private cellRenderKind;
+    private renderStructuralCell;
     private appendEditableIndicator;
     private releaseSlotEditors;
     private treeColumnCache;
@@ -1859,6 +1980,7 @@ declare class GridCore<TData = any> {
     readonly editingService: EditingService;
     readonly undoService: UndoRedoService;
     readonly changeTracker: ChangeTrackingService<TData>;
+    readonly performanceMonitor: PerformanceMonitor;
     readonly filterPopup: FilterPopupService;
     readonly columnMenu: ColumnMenuService;
     readonly contextMenuService: ContextMenuService;
@@ -1886,6 +2008,7 @@ declare class GridCore<TData = any> {
     private settleReady;
     resolveCellRenderer(name: string): CellRendererFn | undefined;
     resolveCellEditor(name: string): CellEditorFactory | undefined;
+    private inactiveFeatureDependency;
     setFeatures(features: readonly GridFeature<TData>[] | null | undefined): void;
     private destroyFeatures;
     isDestroyed(): boolean;
@@ -1922,6 +2045,9 @@ declare class GridCore<TData = any> {
     applyQuickFilter(): void;
     moveColumn(colId: string, toIndex: number): void;
     toggleDetail(rowId: string): boolean;
+    emitColumnResize(column: Column, finished: boolean): void;
+    /** Finalizes one logical resize operation and persists its state once. */
+    commitColumnWidths(columns: readonly Column[]): void;
     private columnStateLoadToken;
     loadPersistedColumnState(): void;
     persistColumnState(): void;
@@ -1957,6 +2083,15 @@ declare function computeColumnWidths(cols: WidthInput[], availableWidth: number)
 /** Fits columns into a viewport while honoring every min/max bound. */
 declare function fitColumnWidths(cols: WidthInput[], availableWidth: number): number[];
 
+declare function normalizeColumnFilter(input: unknown): ColumnFilter | null;
+/** Clones and bounds untrusted JSON before it reaches the row pipeline. */
+declare function normalizeAdvancedFilterModel(input: unknown, validColumnIds?: ReadonlySet<string>): AdvancedFilterModel | null;
+declare function advancedFilterCondition(colId: string, filter: ColumnFilter): AdvancedFilterCondition;
+declare function normalizeFilterModel(input: unknown, validColumnIds?: ReadonlySet<string>): FilterModel;
+declare function advancedFilterGroup(operator: "and" | "or", children: AdvancedFilterNode[], options?: {
+    not?: boolean;
+}): AdvancedFilterGroup;
+
 interface GridSizePreset {
     rowHeight: number;
     headerHeight: number;
@@ -2022,6 +2157,10 @@ declare const GRID_OPTION_META: {
         readonly kind: "string";
         readonly update: "options";
     };
+    readonly enableColumnResize: {
+        readonly kind: "boolean";
+        readonly update: "options";
+    };
     readonly domLayout: {
         readonly kind: "string";
         readonly update: "options";
@@ -2054,6 +2193,10 @@ declare const GRID_OPTION_META: {
         readonly kind: "string";
         readonly update: "quickFilter";
     };
+    readonly advancedFilterModel: {
+        readonly kind: "object";
+        readonly update: "options";
+    };
     readonly masterDetail: {
         readonly kind: "boolean";
         readonly update: "options";
@@ -2334,6 +2477,14 @@ declare const GRID_OPTION_META: {
 declare const GRID_OPTION_KEYS: readonly GridOptionKey[];
 declare const DIRECT_GRID_OPTION_KEYS: readonly GridOptionKey[];
 
+declare function matchesGridOptionKind(value: unknown, kind: GridOptionValueKind): boolean;
+/**
+ * Drops unknown and runtime-invalid options before they can partially mutate a grid.
+ * Validation still reports the original patch, while this function guarantees that
+ * JavaScript/JSON callers receive the same safety boundary as TypeScript callers.
+ */
+declare function sanitizeGridOptionPatch<TData>(input: Partial<GridOptions<TData>> | Record<string, unknown>): Partial<GridOptions<TData>>;
+
 declare function describeFilter(filter: ColumnFilter): string;
 
 type GridValidationCode = "UNKNOWN_OPTION" | "INVALID_OPTION_VALUE" | "OPTION_CONFLICT" | "MISSING_STABLE_ROW_ID";
@@ -2346,6 +2497,23 @@ interface GridValidationIssue {
 /** Runtime validation for JavaScript, JSON/schema driven and dynamic options. */
 declare function validateGridOptions(options: Partial<GridOptions<any>> | Record<string, unknown>): GridValidationIssue[];
 
+type GridFeatureIssueCode = "DUPLICATE_FEATURE" | "FEATURE_CONFLICT" | "FEATURE_CYCLE" | "FEATURE_DEPENDENCY_SETUP_FAILED" | "INVALID_FEATURE_KEY" | "MISSING_FEATURE_DEPENDENCY";
+interface GridFeatureIssue {
+    code: GridFeatureIssueCode;
+    feature?: string;
+    dependency?: string;
+    message: string;
+}
+interface ResolvedGridFeatures<TData = any> {
+    features: GridFeature<TData>[];
+    issues: GridFeatureIssue[];
+}
+/**
+ * Validates and dependency-orders per-grid features before any setup side effect runs.
+ * Invalid features are isolated instead of leaving a partially initialised extension graph.
+ */
+declare function resolveGridFeatures<TData>(input: readonly GridFeature<TData>[]): ResolvedGridFeatures<TData>;
+
 type GridSchemaFieldType = "string" | "number" | "date" | "select" | "boolean";
 interface SchemaSelectOption {
     label: string;
@@ -2423,7 +2591,7 @@ declare function loadColumnState(key: string): ColumnState[] | null;
 declare function clearColumnState(key: string): void;
 
 interface StoredGridState {
-    schemaVersion: 1;
+    schemaVersion: 2;
     savedAt: number;
     state: GridState;
 }
@@ -2440,7 +2608,7 @@ interface ManagedGridStateStore extends GridStateStore {
 }
 /** Safe, versioned localStorage adapter for full grid state. */
 declare function createLocalGridStateStore(options?: LocalGridStateStoreOptions): ManagedGridStateStore;
-declare function saveGridState(key: string, state: GridState): void;
+declare function saveGridState(key: string, state: GridStateInput): void;
 declare function loadGridState(key: string): GridState | null;
 declare function clearGridState(key: string): void;
 
@@ -2685,10 +2853,68 @@ interface DictionaryRendererOptions {
 /** 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 createSaveSnapshot<TData>(changes: readonly GridChange<TData>[], rowIds?: readonly string[]): GridChange<TData>[];
+declare function normalizeBatchSaveResult<TData>(submitted: GridChange<TData>[], response: void | SaveChangesResult<TData>): GridBatchSaveResult<TData>;
+declare function resolveSaveConflict<TData>(api: GridApi<TData>, conflict: SaveChangeConflict<TData>, strategy: "acceptServer" | "keepLocal"): boolean;
+
+/** Migrates and bounds persisted state before it mutates a live grid. */
+declare function migrateGridState(input: unknown): GridState | null;
+
+/** Portable user preference snapshot. Selection and row expansion are deliberately excluded. */
+interface GridViewState {
+    version: 1;
+    columns: ColumnState[];
+    sortModel: SortModel;
+    filterModel: FilterModel;
+    advancedFilterModel: AdvancedFilterModel | null;
+    quickFilterText: string | null;
+    pageSize: number;
+}
+interface SavedGridView {
+    schemaVersion: 1;
+    id: string;
+    name: string;
+    createdAt: number;
+    updatedAt: number;
+    state: GridViewState;
+}
+interface GridViewStore {
+    list(scope: string): readonly SavedGridView[] | Promise<readonly SavedGridView[]>;
+    save(scope: string, view: SavedGridView): void | Promise<void>;
+    remove(scope: string, id: string): void | Promise<void>;
+}
+interface GridViewManager {
+    list(): Promise<SavedGridView[]>;
+    save(name: string, id?: string): Promise<SavedGridView>;
+    apply(viewOrId: SavedGridView | string, options?: {
+        emitEvents?: boolean;
+    }): Promise<SavedGridView>;
+    remove(id: string): Promise<void>;
+}
+
+interface LocalGridViewStoreOptions {
+    namespace?: string;
+    storage?: ColumnStateStorage;
+    maxViews?: number;
+    maxBytes?: number;
+    onError?(error: unknown, operation: "list" | "save" | "remove", scope: string): void;
+}
+declare function normalizeGridViewState(input: unknown): GridViewState | null;
+declare function normalizeSavedGridView(input: unknown): SavedGridView | null;
+declare function captureGridViewState<TData>(api: GridApi<TData>): GridViewState;
+declare function applyGridViewState<TData>(api: GridApi<TData>, view: GridViewState, options?: {
+    emitEvents?: boolean;
+}): boolean;
+declare function createLocalGridViewStore(options?: LocalGridViewStoreOptions): GridViewStore;
+declare function createGridViewManager<TData>(api: GridApi<TData>, options: {
+    scope: string;
+    store?: GridViewStore;
+}): GridViewManager;
+
 declare function evaluateColumnFilter(value: any, filter: ColumnFilter): boolean;
 
 declare function sortNodes<TData>(nodes: RowNode<TData>[], sortModel: SortModel, columns: Column[], getCellValue: (node: RowNode<TData>, column: Column) => any): RowNode<TData>[];
 
 declare const version: string;
 
-export { type ActionButtonsConfig, type ActionItem, type ActionOverflowMode, type ActionPolicy, type ActionPolicyContext, type ActionVariant, type AggFunction, type AggValues, type ApplyGridStateOptions, BUILTIN_AGG_FUNCS, type BuiltInActionIcon, 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, type DomLayoutMode, 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 GridStateStore, type GridValidationCode, type GridValidationIssue, type HeaderComponentParams, type ICellEditor, type ICellRendererResult, type ImportCsvOptions, type InfiniteGetRowsParams, LOCALE_EN, type LocalColumnStateStoreOptions, type LocalGridStateStoreOptions, type MachTableCommandOptions, type MachTableCommands, type MachTableConfigWarning, type MachTableOptionExplanation, type MachTablePresetSelection, type MachTableRuntimeConfig, type ManagedColumnStateStore, type ManagedGridStateStore, 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 ResolvedMachTableConfig, type ResolvedMachTableGridOptions, 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 StoredGridState, 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, clearGridState, computeColumnWidths, createActionButtonsRenderer, createAggResolver, createBusinessColumnTypes, createCachedDictionary, createColumnHelper, createColumnStateKey, createDictionaryRenderer, createEnterprisePreset, createGrid, createLocalColumnStateStore, createLocalGridStateStore, createMachTableCommands, createMachTablePreset, createProgressBarRenderer, createRowActionsRenderer, createStatusTagRenderer, defaultComparator, defineColumns, defineGridOptions, defineMachTableConfig, defineMachTablePreset, describeFilter, downloadFile, dragColumn, escapeHtml, evaluateColumnFilter, fitColumnWidths, formatText, formatTwo, getByPath, getCellEditor, getCellRenderer, indexColumn, isColDefGroup, isSafePath, linkRenderer, loadColumnState, loadGridState, matchLocaleKey, mergeMachTableConfig, normalizeMachTableConfig, parseCsv, parseDelimited, parseTsv, registerBuiltinRenderers, registerCellEditor, registerCellRenderer, resolveMachTableGridOptions, resolveTagVariant, rowActionsColumn, sanitizeFormulaCell, saveColumnState, saveGridState, selectionColumn, setByPath, sortNodes, toTsv, validateGridOptions, version };
+export { type ActionButtonsConfig, type ActionItem, type ActionOverflowMode, type ActionPolicy, type ActionPolicyContext, type ActionVariant, type AdvancedFilterCondition, type AdvancedFilterGroup, type AdvancedFilterModel, type AdvancedFilterNode, type AggFunction, type AggValues, type ApplyGridStateOptions, BUILTIN_AGG_FUNCS, type BuiltInActionIcon, 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, type DomLayoutMode, 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 GridBatchSaveResult, 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 GridFeatureIssue, type GridFeatureIssueCode, type GridOptionKey, type GridOptionMetadata, type GridOptionUpdateMode, type GridOptionValueKind, type GridOptions, type GridPerformanceSnapshot, type GridReadyEvent, type GridSchema, type GridSchemaField, type GridSchemaFieldType, type GridSchemaGroup, type GridSize, type GridSizePreset, type GridState, type GridStateInput, type GridStateSection, type GridStateStore, type GridValidationCode, type GridValidationIssue, type GridViewManager, type GridViewState, type GridViewStore, type HeaderComponentParams, type ICellEditor, type ICellRendererResult, type ImportCsvOptions, type InfiniteGetRowsParams, LOCALE_EN, type LegacyGridStateV1, type LocalColumnStateStoreOptions, type LocalGridStateStoreOptions, type LocalGridViewStoreOptions, type MachTableCommandOptions, type MachTableCommands, type MachTableConfigWarning, type MachTableOptionExplanation, type MachTablePresetSelection, type MachTableRuntimeConfig, type ManagedColumnStateStore, type ManagedGridStateStore, type ModelUpdatedEvent, type NumberFilterCondition, type NumberFilterMatch, type OverlayContent, type OverlayTemplate, type PaginationChangedEvent, type PaginationConfig, type PinnedDirection, type PrintOptions, type ProgressConfig, type RangeSelectionChangedEvent, type ResolvedGridFeatures, type ResolvedGridOptions, type ResolvedMachTableConfig, type ResolvedMachTableGridOptions, 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 SaveChangeConflict, type SaveChangeIssue, type SaveChangesHandler, type SaveChangesResult, type SavedGridView, 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 StoredGridState, 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, advancedFilterCondition, advancedFilterGroup, applyGridViewState, buildColDefsFromSchema, captureGridViewState, clearColumnState, clearComponentRegistries, clearGridState, computeColumnWidths, createActionButtonsRenderer, createAggResolver, createBusinessColumnTypes, createCachedDictionary, createColumnHelper, createColumnStateKey, createDictionaryRenderer, createEnterprisePreset, createGrid, createGridViewManager, createLocalColumnStateStore, createLocalGridStateStore, createLocalGridViewStore, createMachTableCommands, createMachTablePreset, createProgressBarRenderer, createRowActionsRenderer, createSaveSnapshot, createStatusTagRenderer, defaultComparator, defineColumns, defineGridOptions, defineMachTableConfig, defineMachTablePreset, describeFilter, downloadFile, dragColumn, escapeHtml, evaluateColumnFilter, fitColumnWidths, formatText, formatTwo, getByPath, getCellEditor, getCellRenderer, indexColumn, isColDefGroup, isSafePath, linkRenderer, loadColumnState, loadGridState, matchLocaleKey, matchesGridOptionKind, mergeMachTableConfig, migrateGridState, normalizeAdvancedFilterModel, normalizeBatchSaveResult, normalizeColumnFilter, normalizeFilterModel, normalizeGridViewState, normalizeMachTableConfig, normalizeSavedGridView, parseCsv, parseDelimited, parseTsv, registerBuiltinRenderers, registerCellEditor, registerCellRenderer, resolveGridFeatures, resolveMachTableGridOptions, resolveSaveConflict, resolveTagVariant, rowActionsColumn, sanitizeFormulaCell, sanitizeGridOptionPatch, saveColumnState, saveGridState, selectionColumn, setByPath, sortNodes, toTsv, validateGridOptions, version };