@agile-team/mach-table 0.13.0 → 0.15.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> {
@@ -303,6 +305,15 @@ declare const DEFAULT_LOCALE: {
     readonly pagePrev: "上一页";
     readonly pageNext: "下一页";
     readonly pageLast: "末页";
+    readonly requestFailed: "数据加载失败";
+    readonly requestFailedHint: "请检查网络后重试";
+    readonly actionView: "查看";
+    readonly actionEdit: "编辑";
+    readonly actionDelete: "删除";
+    readonly actionConfirm: "确认";
+    readonly actionSave: "保存";
+    readonly actionCancel: "取消";
+    readonly actionMore: "更多操作";
 };
 type RgLocaleKey = keyof typeof DEFAULT_LOCALE;
 type RgLocale = Partial<Record<RgLocaleKey, string>>;
@@ -336,10 +347,31 @@ interface ApplyGridStateOptions {
     emitEvents?: boolean;
 }
 
+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;
+};
+/** Dot-separated path to a serializable field, capped to keep editor inference fast. */
+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 ColumnStateStore {
     load(key: string): ColumnState[] | null | Promise<ColumnState[] | null>;
     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>;
+    clear?(key: string): void | Promise<void>;
+}
 /** Per-grid component overrides. These take precedence over the global registry. */
 interface GridComponents {
     cellRenderers?: Readonly<Record<string, CellRendererFn>>;
@@ -392,6 +424,7 @@ type EventHandlers<TData = any> = {
 type RowSelectionMode = "none" | "single" | "multiple";
 type GridSize = "compact" | "normal" | "large";
 type ColumnLayoutMode = "normal" | "fit";
+type DomLayoutMode = "normal" | "autoHeight";
 type ThemeMode = "light" | "dark" | "auto";
 type GridEditType = "cell" | "fullRow";
 type EditableIndicator = "hover" | "always" | "none";
@@ -458,11 +491,17 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
     /** Reusable semantic column definitions referenced through `colDef.type`. */
     columnTypes?: Readonly<Record<string, Partial<ColDef<TData>>>>;
     getRowId?: (params: GetRowIdParams<TData>) => string;
+    /** Stable business key shorthand. `getRowId` takes precedence when both are set. */
+    rowKey?: FieldPath<TData> | ((row: TData) => string | number);
     rowHeight?: number;
     headerHeight?: number;
     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;
     multiSort?: boolean;
     size?: GridSize;
@@ -485,6 +524,10 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
     features?: readonly GridFeature<TData>[];
     /** State restored atomically after columns and initial rows are available. */
     initialState?: GridState;
+    /** Persist the complete user-visible GridState with a versioned store. */
+    stateKey?: string | null;
+    stateStore?: GridStateStore;
+    stateSaveDebounceMs?: number;
     locale?: RgLocale;
     /** Cell editing is isolated; fullRow stages every editable cell and commits them together. */
     editType?: GridEditType;
@@ -547,8 +590,11 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
     /** ID of an external element that provides additional grid instructions. */
     ariaDescribedBy?: string;
     loading?: boolean;
+    /** Non-null errors take precedence over the empty state and remain retryable by the host. */
+    error?: unknown | null;
     overlayNoRowsTemplate?: OverlayTemplate;
     overlayLoadingTemplate?: OverlayTemplate;
+    overlayErrorTemplate?: OverlayTemplate;
     /** Opt in only for trusted overlay strings. Prefer HTMLElement factories. */
     allowUnsafeOverlayHtml?: boolean;
     className?: string;
@@ -559,10 +605,13 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     defaultColDef: Partial<ColDef<TData>>;
     columnTypes: Readonly<Record<string, Partial<ColDef<TData>>>>;
     getRowId?: (params: GetRowIdParams<TData>) => string;
+    rowKey?: FieldPath<TData> | ((row: TData) => string | number);
     rowHeight: number;
     headerHeight: number;
     rowBuffer: number;
     columnLayout: ColumnLayoutMode;
+    enableColumnResize: boolean;
+    domLayout: DomLayoutMode;
     rowSelection: RowSelectionMode;
     multiSort: boolean;
     size: GridSize;
@@ -583,6 +632,9 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     actionPolicy?: ActionPolicy<TData>;
     features: readonly GridFeature<TData>[];
     initialState?: GridState;
+    stateKey: string | null;
+    stateStore?: GridStateStore;
+    stateSaveDebounceMs: number;
     locale: RgLocale;
     editType: GridEditType;
     editableIndicator: EditableIndicator;
@@ -643,8 +695,10 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
     ariaLabelledBy: string;
     ariaDescribedBy: string;
     loading: boolean;
+    error: unknown | null;
     overlayNoRowsTemplate: OverlayTemplate;
     overlayLoadingTemplate: OverlayTemplate;
+    overlayErrorTemplate: OverlayTemplate;
     allowUnsafeOverlayHtml: boolean;
     className: string;
 }
@@ -727,6 +781,8 @@ type SaveChangesHandler<TData = any> = (changes: readonly GridChange<TData>[]) =
 interface GridApi<TData = any> {
     /** Resolves after the first layout frame and gridReady emission. */
     whenReady(): Promise<GridApi<TData>>;
+    /** Stable grid root for portals, measurements and fullscreen targets; null after destroy. */
+    getRootElement(): HTMLElement | null;
     /** 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. */
@@ -745,6 +801,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;
@@ -845,7 +903,7 @@ interface GridApi<TData = any> {
     applyState(state: GridState, options?: ApplyGridStateOptions): void;
     /** Lightweight runtime snapshot suitable for support logs and health panels. */
     getDiagnostics(): GridDiagnostics;
-    setOverlay(type: "loading" | "noRows" | null): void;
+    setOverlay(type: "loading" | "noRows" | "error" | null): void;
     hideOverlays(): void;
     addEventListener<K extends GridEventType>(eventType: K, listener: (event: GridEventMap<TData>[K]) => void): () => void;
     removeEventListener<K extends GridEventType>(eventType: K, listener: (event: GridEventMap<TData>[K]) => void): void;
@@ -1069,6 +1127,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;
@@ -1122,12 +1184,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;
@@ -1284,16 +1348,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;
 }
 
@@ -1559,15 +1632,17 @@ declare class GridSkeleton {
     private systemPrefersDark;
     setStriped(on: boolean): void;
     setCellBorders(on: boolean): void;
+    applyDomLayout(layout: DomLayoutMode): void;
     setCustomClass(className: string | null | undefined): void;
-    showOverlay(type: "loading" | "noRows", content: OverlayTemplate, allowUnsafeHtml?: boolean): void;
+    showOverlay(type: "loading" | "noRows" | "error", content: OverlayTemplate, allowUnsafeHtml?: boolean): void;
     hideOverlay(): void;
+    private applyOverlayRole;
     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">;
+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;
@@ -1581,6 +1656,7 @@ declare class HeaderRenderer {
     private visiblePaneLeaves;
     private onHeaderKeyDown;
     private focusHeaderCell;
+    private canResizeColumn;
     refreshSortIndicators(): void;
     refreshFilterIcons(): void;
     refreshSelectAllCheckbox(): void;
@@ -1594,7 +1670,7 @@ interface NormalizedRange {
     c2: number;
 }
 
-type BodyContext = Pick<GridCore<any>, "buildDefaultEmptyState" | "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" | "pinnedRowsRenderer" | "reportError" | "resolveCellRenderer" | "rowModel" | "selectionService" | "setCellValue" | "skeleton" | "summaryRenderer" | "toggleDetail" | "tooltipService" | "undoService">;
 interface FocusedCell {
     rowIndex: number;
     colId: string;
@@ -1628,6 +1704,7 @@ declare class BodyRenderer {
     private measureCanvas;
     applyContainerSizes(): void;
     invalidateRowHeight(node: RowNode<any>): void;
+    private applyDomLayoutHeight;
     invalidateAllRowHeights(): void;
     private collectAutoHeightColumns;
     private get hasAnyAutoHeight();
@@ -1643,6 +1720,8 @@ declare class BodyRenderer {
     applyCellLayout(): void;
     private computeColWindow;
     updateRange(force?: boolean): void;
+    private reconcileColumnWindow;
+    private renderAutoHeightRange;
     private hideSlot;
     private assignSlot;
     private renderPaneCells;
@@ -1822,6 +1901,8 @@ declare class GridCore<TData = any> {
     private lastColumnLayoutSignature;
     private activeFeatures;
     private recentErrors;
+    private stateSaveTimer;
+    private gridStateLoadToken;
     constructor(container: HTMLElement, options: GridOptions<TData>);
     getApi(): GridApi<TData>;
     whenReady(): Promise<GridApi<TData>>;
@@ -1864,9 +1945,16 @@ declare class GridCore<TData = any> {
     applyQuickFilter(): void;
     moveColumn(colId: string, toIndex: number): void;
     toggleDetail(rowId: string): boolean;
-    private stateLoadToken;
+    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;
+    loadPersistedGridState(): void;
+    scheduleGridStateSave(): void;
+    persistGridState(): void;
+    buildDefaultErrorState(): HTMLElement;
     buildDefaultEmptyState(): HTMLElement;
     private lastValidatedDefs;
     private issuedWarningSignatures;
@@ -1940,6 +2028,10 @@ declare const GRID_OPTION_META: {
         readonly kind: "function";
         readonly update: "options";
     };
+    readonly rowKey: {
+        readonly kind: "unknown";
+        readonly update: "options";
+    };
     readonly rowHeight: {
         readonly kind: "number";
         readonly update: "options";
@@ -1956,6 +2048,14 @@ 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";
+    };
     readonly rowSelection: {
         readonly kind: "string";
         readonly update: "options";
@@ -2036,6 +2136,18 @@ declare const GRID_OPTION_META: {
         readonly kind: "object";
         readonly update: "options";
     };
+    readonly stateKey: {
+        readonly kind: "string";
+        readonly update: "options";
+    };
+    readonly stateStore: {
+        readonly kind: "object";
+        readonly update: "options";
+    };
+    readonly stateSaveDebounceMs: {
+        readonly kind: "number";
+        readonly update: "options";
+    };
     readonly locale: {
         readonly kind: "object";
         readonly update: "options";
@@ -2224,6 +2336,10 @@ declare const GRID_OPTION_META: {
         readonly kind: "boolean";
         readonly update: "options";
     };
+    readonly error: {
+        readonly kind: "unknown";
+        readonly update: "options";
+    };
     readonly overlayNoRowsTemplate: {
         readonly kind: "unknown";
         readonly update: "options";
@@ -2232,6 +2348,10 @@ declare const GRID_OPTION_META: {
         readonly kind: "unknown";
         readonly update: "options";
     };
+    readonly overlayErrorTemplate: {
+        readonly kind: "unknown";
+        readonly update: "options";
+    };
     readonly allowUnsafeOverlayHtml: {
         readonly kind: "boolean";
         readonly update: "options";
@@ -2332,6 +2452,28 @@ declare function saveColumnState(key: string, state: ColumnState[]): void;
 declare function loadColumnState(key: string): ColumnState[] | null;
 declare function clearColumnState(key: string): void;
 
+interface StoredGridState {
+    schemaVersion: 1;
+    savedAt: number;
+    state: GridState;
+}
+interface LocalGridStateStoreOptions {
+    namespace?: string;
+    storage?: ColumnStateStorage;
+    /** Reject unexpectedly large or corrupted payloads. Defaults to 512 KiB. */
+    maxBytes?: number;
+    onError?(error: unknown, operation: "load" | "save" | "clear", key: string): void;
+}
+interface ManagedGridStateStore extends GridStateStore {
+    clear(key: string): void;
+    storageKey(key: string): string;
+}
+/** Safe, versioned localStorage adapter for full grid state. */
+declare function createLocalGridStateStore(options?: LocalGridStateStoreOptions): ManagedGridStateStore;
+declare function saveGridState(key: string, state: GridState): void;
+declare function loadGridState(key: string): GridState | null;
+declare function clearGridState(key: string): void;
+
 type AggValues = Record<string, any>;
 type AggFunction = (values: any[]) => any;
 declare const BUILTIN_AGG_FUNCS: Record<string, AggFunction>;
@@ -2345,6 +2487,29 @@ declare function parseDelimited(text: string, separator: string): string[][];
 declare function escapeHtml(value: any): string;
 declare function downloadFile(filename: string, content: string, mime?: string): boolean;
 
+interface MachTableCommandOptions<TData = any> {
+    getApi(): GridApi<TData> | null;
+    /** Overrides refresh for remote-query workflows. */
+    reload?: () => void | Promise<void>;
+    /** Fullscreen target. Defaults to the grid root's parent when available. */
+    getFullscreenElement?: () => HTMLElement | null;
+}
+interface MachTableCommands {
+    search(text: string | null | undefined): void;
+    refresh(): Promise<void>;
+    openColumns(anchor?: HTMLElement): void;
+    setDensity(size: GridSize): void;
+    resetColumns(): void;
+    undo(): boolean;
+    redo(): boolean;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    exportCsv(filename?: string): boolean;
+    toggleFullscreen(): Promise<boolean>;
+}
+/** Framework-neutral command surface used by Vue/React controllers and toolbars. */
+declare function createMachTableCommands<TData = any>(options: MachTableCommandOptions<TData>): MachTableCommands;
+
 declare function sanitizeFormulaCell(value: any): any;
 
 declare function registerCellRenderer(name: string, renderer: CellRendererFn): () => void;
@@ -2367,12 +2532,26 @@ interface ProgressConfig {
 }
 declare function createProgressBarRenderer(config?: ProgressConfig): CellRendererFn;
 declare function linkRenderer(params: CellRendererParams): string | HTMLElement;
+declare const ICON_PATHS: {
+    readonly edit: "<path d=\"M11.5 2.5l2 2L5 13H3v-2l8.5-8.5z\"/>";
+    readonly delete: "<path d=\"M3 5h10M6 5V3h4v2M5 5l.7 8h4.6L11 5\"/>";
+    readonly view: "<path d=\"M1.5 8s2.4-4.2 6.5-4.2S14.5 8 14.5 8s-2.4 4.2-6.5 4.2S1.5 8 1.5 8z\"/><circle cx=\"8\" cy=\"8\" r=\"1.8\"/>";
+    readonly copy: "<rect x=\"5\" y=\"5\" width=\"8\" height=\"8\" rx=\"1\"/><path d=\"M3 11V3h8\"/>";
+    readonly download: "<path d=\"M8 2v8m0 0l-3-3m3 3l3-3M2.5 13.5h11\"/>";
+    readonly refresh: "<path d=\"M13 3v4h-4M3 13V9h4\"/><path d=\"M13 7a5.5 5.5 0 00-9.7-2.6M3 9a5.5 5.5 0 009.7 2.6\"/>";
+    readonly close: "<path d=\"M3.5 3.5l9 9m0-9l-9 9\"/>";
+    readonly check: "<path d=\"M2.5 8.5l3.5 3.5 7.5-8\"/>";
+    readonly plus: "<path d=\"M8 2.5v11M2.5 8h11\"/>";
+    readonly search: "<circle cx=\"7\" cy=\"7\" r=\"4.5\"/><path d=\"M10.5 10.5L14 14\"/>";
+    readonly more: "<circle cx=\"3\" cy=\"8\" r=\".9\" fill=\"currentColor\" stroke=\"none\"/><circle cx=\"8\" cy=\"8\" r=\".9\" fill=\"currentColor\" stroke=\"none\"/><circle cx=\"13\" cy=\"8\" r=\".9\" fill=\"currentColor\" stroke=\"none\"/>";
+};
+type BuiltInActionIcon = keyof typeof ICON_PATHS;
 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;
+    icon?: BuiltInActionIcon;
     label?: string;
     title?: string;
     /** Backwards-compatible shorthand for variant="danger". */
@@ -2398,10 +2577,12 @@ interface ActionButtonsConfig<TData = any> {
 interface RowActionsConfig<TData = any> extends Omit<ActionButtonsConfig<TData>, "actions"> {
     onView?: (params: CellRendererParams<TData>) => unknown | Promise<unknown>;
     onDelete?: (params: CellRendererParams<TData>) => unknown | Promise<unknown>;
+    /** Persists the just-validated row. Failures reopen row editing and keep the change dirty. */
+    onSave?: (params: CellRendererParams<TData>, changes: readonly GridChange<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>>;
+    labels?: Partial<Record<"view" | "edit" | "delete" | "confirm" | "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>);
@@ -2422,20 +2603,6 @@ declare function rowActionsColumn<TData = any>(config?: RowActionsConfig<TData>
     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>;
@@ -2455,6 +2622,51 @@ declare function defineMachTablePreset<TData>(preset: Partial<GridOptions<TData>
 /** Compile-time helper for reusable, typed grid option objects. */
 declare function defineGridOptions<TData>(options: GridOptions<TData>): GridOptions<TData>;
 
+type MachTablePresetSelection = string | readonly string[] | false | null;
+interface MachTableConfigWarning {
+    code: "UNKNOWN_PRESET";
+    message: string;
+    preset?: string;
+}
+interface MachTableRuntimeConfig {
+    /** Defaults inherited by every table in this application or subtree. */
+    defaults?: Partial<GridOptions<any>>;
+    /** Application-wide semantic column types. Kept separate for config readability. */
+    columnTypes?: Readonly<Record<string, Partial<ColDef<any>>>>;
+    /** Application-wide renderer/editor registry. Per-table components can override it. */
+    components?: GridComponents;
+    /** Named, reusable behavior profiles such as `list`, `crud` or `picker`. */
+    presets?: Readonly<Record<string, Partial<GridOptions<any>>>>;
+    /** Preset used when a table does not declare its own preset. Set false to disable. */
+    defaultPreset?: MachTablePresetSelection;
+    onConfigWarning?: (warning: MachTableConfigWarning) => void;
+}
+interface ResolvedMachTableConfig {
+    readonly defaults: Partial<GridOptions<any>>;
+    readonly presets: Readonly<Record<string, Partial<GridOptions<any>>>>;
+    readonly defaultPreset: MachTablePresetSelection;
+    readonly onConfigWarning?: (warning: MachTableConfigWarning) => void;
+}
+interface MachTableOptionExplanation {
+    readonly key: keyof GridOptions<any> | string;
+    readonly value: unknown;
+    readonly source: string;
+    readonly layers: readonly {
+        name: string;
+        value: unknown;
+    }[];
+}
+interface ResolvedMachTableGridOptions<TData = any> {
+    readonly options: GridOptions<TData>;
+    explain(key: keyof GridOptions<TData> | string): MachTableOptionExplanation;
+}
+/** Type-checks a dedicated `mach-table.config.ts` without runtime work. */
+declare function defineMachTableConfig<const TConfig extends MachTableRuntimeConfig>(config: TConfig): TConfig;
+declare function normalizeMachTableConfig(config?: MachTableRuntimeConfig): ResolvedMachTableConfig;
+/** Merges app, route and layout configuration while preserving named presets. */
+declare function mergeMachTableConfig(parent: ResolvedMachTableConfig, child: MachTableRuntimeConfig): ResolvedMachTableConfig;
+declare function resolveMachTableGridOptions<TData>(config: ResolvedMachTableConfig, requestedPreset: MachTablePresetSelection | undefined, explicit: Partial<GridOptions<TData>>, reportWarning?: (warning: MachTableConfigWarning) => void): ResolvedMachTableGridOptions<TData>;
+
 type BusinessColumnType = "text" | "number" | "integer" | "money" | "percent" | "percentage" | "date" | "datetime" | "boolean" | "status" | "link";
 interface BusinessColumnTypeOptions {
     locale?: string | readonly string[];
@@ -2509,4 +2721,4 @@ declare function sortNodes<TData>(nodes: RowNode<TData>[], sortModel: SortModel,
 
 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 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 };
+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 };