@agile-team/mach-table 0.13.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -303,6 +303,15 @@ declare const DEFAULT_LOCALE: {
303
303
  readonly pagePrev: "上一页";
304
304
  readonly pageNext: "下一页";
305
305
  readonly pageLast: "末页";
306
+ readonly requestFailed: "数据加载失败";
307
+ readonly requestFailedHint: "请检查网络后重试";
308
+ readonly actionView: "查看";
309
+ readonly actionEdit: "编辑";
310
+ readonly actionDelete: "删除";
311
+ readonly actionConfirm: "确认";
312
+ readonly actionSave: "保存";
313
+ readonly actionCancel: "取消";
314
+ readonly actionMore: "更多操作";
306
315
  };
307
316
  type RgLocaleKey = keyof typeof DEFAULT_LOCALE;
308
317
  type RgLocale = Partial<Record<RgLocaleKey, string>>;
@@ -336,10 +345,31 @@ interface ApplyGridStateOptions {
336
345
  emitEvents?: boolean;
337
346
  }
338
347
 
348
+ type Callable = (...args: never[]) => unknown;
349
+ type Primitive = string | number | boolean | bigint | symbol | null | undefined | Date | Callable;
350
+ type Depth = 0 | 1 | 2 | 3 | 4;
351
+ type Previous = {
352
+ 0: 0;
353
+ 1: 0;
354
+ 2: 1;
355
+ 3: 2;
356
+ 4: 3;
357
+ };
358
+ /** Dot-separated path to a serializable field, capped to keep editor inference fast. */
359
+ type FieldPath<T, D extends Depth = 4> = D extends 0 ? never : T extends Primitive ? never : {
360
+ [K in keyof T & string]: NonNullable<T[K]> extends Primitive | readonly unknown[] ? K : K | `${K}.${FieldPath<NonNullable<T[K]>, Previous[D]>}`;
361
+ }[keyof T & string];
362
+ 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;
363
+
339
364
  interface ColumnStateStore {
340
365
  load(key: string): ColumnState[] | null | Promise<ColumnState[] | null>;
341
366
  save(key: string, state: ColumnState[]): void | Promise<void>;
342
367
  }
368
+ interface GridStateStore {
369
+ load(key: string): GridState | null | Promise<GridState | null>;
370
+ save(key: string, state: GridState): void | Promise<void>;
371
+ clear?(key: string): void | Promise<void>;
372
+ }
343
373
  /** Per-grid component overrides. These take precedence over the global registry. */
344
374
  interface GridComponents {
345
375
  cellRenderers?: Readonly<Record<string, CellRendererFn>>;
@@ -392,6 +422,7 @@ type EventHandlers<TData = any> = {
392
422
  type RowSelectionMode = "none" | "single" | "multiple";
393
423
  type GridSize = "compact" | "normal" | "large";
394
424
  type ColumnLayoutMode = "normal" | "fit";
425
+ type DomLayoutMode = "normal" | "autoHeight";
395
426
  type ThemeMode = "light" | "dark" | "auto";
396
427
  type GridEditType = "cell" | "fullRow";
397
428
  type EditableIndicator = "hover" | "always" | "none";
@@ -458,11 +489,15 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
458
489
  /** Reusable semantic column definitions referenced through `colDef.type`. */
459
490
  columnTypes?: Readonly<Record<string, Partial<ColDef<TData>>>>;
460
491
  getRowId?: (params: GetRowIdParams<TData>) => string;
492
+ /** Stable business key shorthand. `getRowId` takes precedence when both are set. */
493
+ rowKey?: FieldPath<TData> | ((row: TData) => string | number);
461
494
  rowHeight?: number;
462
495
  headerHeight?: number;
463
496
  rowBuffer?: number;
464
497
  /** `fit` continuously fills the container without grid-ready glue code. */
465
498
  columnLayout?: ColumnLayoutMode;
499
+ /** Lets small grids grow with their rows. Avoid for large or infinite datasets. */
500
+ domLayout?: DomLayoutMode;
466
501
  rowSelection?: RowSelectionMode;
467
502
  multiSort?: boolean;
468
503
  size?: GridSize;
@@ -485,6 +520,10 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
485
520
  features?: readonly GridFeature<TData>[];
486
521
  /** State restored atomically after columns and initial rows are available. */
487
522
  initialState?: GridState;
523
+ /** Persist the complete user-visible GridState with a versioned store. */
524
+ stateKey?: string | null;
525
+ stateStore?: GridStateStore;
526
+ stateSaveDebounceMs?: number;
488
527
  locale?: RgLocale;
489
528
  /** Cell editing is isolated; fullRow stages every editable cell and commits them together. */
490
529
  editType?: GridEditType;
@@ -547,8 +586,11 @@ interface GridOptions<TData = any> extends EventHandlers<TData> {
547
586
  /** ID of an external element that provides additional grid instructions. */
548
587
  ariaDescribedBy?: string;
549
588
  loading?: boolean;
589
+ /** Non-null errors take precedence over the empty state and remain retryable by the host. */
590
+ error?: unknown | null;
550
591
  overlayNoRowsTemplate?: OverlayTemplate;
551
592
  overlayLoadingTemplate?: OverlayTemplate;
593
+ overlayErrorTemplate?: OverlayTemplate;
552
594
  /** Opt in only for trusted overlay strings. Prefer HTMLElement factories. */
553
595
  allowUnsafeOverlayHtml?: boolean;
554
596
  className?: string;
@@ -559,10 +601,12 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
559
601
  defaultColDef: Partial<ColDef<TData>>;
560
602
  columnTypes: Readonly<Record<string, Partial<ColDef<TData>>>>;
561
603
  getRowId?: (params: GetRowIdParams<TData>) => string;
604
+ rowKey?: FieldPath<TData> | ((row: TData) => string | number);
562
605
  rowHeight: number;
563
606
  headerHeight: number;
564
607
  rowBuffer: number;
565
608
  columnLayout: ColumnLayoutMode;
609
+ domLayout: DomLayoutMode;
566
610
  rowSelection: RowSelectionMode;
567
611
  multiSort: boolean;
568
612
  size: GridSize;
@@ -583,6 +627,9 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
583
627
  actionPolicy?: ActionPolicy<TData>;
584
628
  features: readonly GridFeature<TData>[];
585
629
  initialState?: GridState;
630
+ stateKey: string | null;
631
+ stateStore?: GridStateStore;
632
+ stateSaveDebounceMs: number;
586
633
  locale: RgLocale;
587
634
  editType: GridEditType;
588
635
  editableIndicator: EditableIndicator;
@@ -643,8 +690,10 @@ interface ResolvedGridOptions<TData = any> extends EventHandlers<TData> {
643
690
  ariaLabelledBy: string;
644
691
  ariaDescribedBy: string;
645
692
  loading: boolean;
693
+ error: unknown | null;
646
694
  overlayNoRowsTemplate: OverlayTemplate;
647
695
  overlayLoadingTemplate: OverlayTemplate;
696
+ overlayErrorTemplate: OverlayTemplate;
648
697
  allowUnsafeOverlayHtml: boolean;
649
698
  className: string;
650
699
  }
@@ -727,6 +776,8 @@ type SaveChangesHandler<TData = any> = (changes: readonly GridChange<TData>[]) =
727
776
  interface GridApi<TData = any> {
728
777
  /** Resolves after the first layout frame and gridReady emission. */
729
778
  whenReady(): Promise<GridApi<TData>>;
779
+ /** Stable grid root for portals, measurements and fullscreen targets; null after destroy. */
780
+ getRootElement(): HTMLElement | null;
730
781
  /** Reads the currently resolved value after application, preset and table overrides. */
731
782
  getGridOption<K extends keyof GridOptions<TData>>(key: K): GridOptions<TData>[K];
732
783
  /** Typed shorthand for updating one runtime option. */
@@ -845,7 +896,7 @@ interface GridApi<TData = any> {
845
896
  applyState(state: GridState, options?: ApplyGridStateOptions): void;
846
897
  /** Lightweight runtime snapshot suitable for support logs and health panels. */
847
898
  getDiagnostics(): GridDiagnostics;
848
- setOverlay(type: "loading" | "noRows" | null): void;
899
+ setOverlay(type: "loading" | "noRows" | "error" | null): void;
849
900
  hideOverlays(): void;
850
901
  addEventListener<K extends GridEventType>(eventType: K, listener: (event: GridEventMap<TData>[K]) => void): () => void;
851
902
  removeEventListener<K extends GridEventType>(eventType: K, listener: (event: GridEventMap<TData>[K]) => void): void;
@@ -1559,9 +1610,11 @@ declare class GridSkeleton {
1559
1610
  private systemPrefersDark;
1560
1611
  setStriped(on: boolean): void;
1561
1612
  setCellBorders(on: boolean): void;
1613
+ applyDomLayout(layout: DomLayoutMode): void;
1562
1614
  setCustomClass(className: string | null | undefined): void;
1563
- showOverlay(type: "loading" | "noRows", content: OverlayTemplate, allowUnsafeHtml?: boolean): void;
1615
+ showOverlay(type: "loading" | "noRows" | "error", content: OverlayTemplate, allowUnsafeHtml?: boolean): void;
1564
1616
  hideOverlay(): void;
1617
+ private applyOverlayRole;
1565
1618
  setInfiniteLoading(active: boolean, text: string): void;
1566
1619
  destroy(): void;
1567
1620
  private cleanupOverlayContent;
@@ -1594,7 +1647,7 @@ interface NormalizedRange {
1594
1647
  c2: number;
1595
1648
  }
1596
1649
 
1597
- 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">;
1650
+ 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">;
1598
1651
  interface FocusedCell {
1599
1652
  rowIndex: number;
1600
1653
  colId: string;
@@ -1628,6 +1681,7 @@ declare class BodyRenderer {
1628
1681
  private measureCanvas;
1629
1682
  applyContainerSizes(): void;
1630
1683
  invalidateRowHeight(node: RowNode<any>): void;
1684
+ private applyDomLayoutHeight;
1631
1685
  invalidateAllRowHeights(): void;
1632
1686
  private collectAutoHeightColumns;
1633
1687
  private get hasAnyAutoHeight();
@@ -1643,6 +1697,8 @@ declare class BodyRenderer {
1643
1697
  applyCellLayout(): void;
1644
1698
  private computeColWindow;
1645
1699
  updateRange(force?: boolean): void;
1700
+ private reconcileColumnWindow;
1701
+ private renderAutoHeightRange;
1646
1702
  private hideSlot;
1647
1703
  private assignSlot;
1648
1704
  private renderPaneCells;
@@ -1822,6 +1878,8 @@ declare class GridCore<TData = any> {
1822
1878
  private lastColumnLayoutSignature;
1823
1879
  private activeFeatures;
1824
1880
  private recentErrors;
1881
+ private stateSaveTimer;
1882
+ private gridStateLoadToken;
1825
1883
  constructor(container: HTMLElement, options: GridOptions<TData>);
1826
1884
  getApi(): GridApi<TData>;
1827
1885
  whenReady(): Promise<GridApi<TData>>;
@@ -1864,9 +1922,13 @@ declare class GridCore<TData = any> {
1864
1922
  applyQuickFilter(): void;
1865
1923
  moveColumn(colId: string, toIndex: number): void;
1866
1924
  toggleDetail(rowId: string): boolean;
1867
- private stateLoadToken;
1925
+ private columnStateLoadToken;
1868
1926
  loadPersistedColumnState(): void;
1869
1927
  persistColumnState(): void;
1928
+ loadPersistedGridState(): void;
1929
+ scheduleGridStateSave(): void;
1930
+ persistGridState(): void;
1931
+ buildDefaultErrorState(): HTMLElement;
1870
1932
  buildDefaultEmptyState(): HTMLElement;
1871
1933
  private lastValidatedDefs;
1872
1934
  private issuedWarningSignatures;
@@ -1940,6 +2002,10 @@ declare const GRID_OPTION_META: {
1940
2002
  readonly kind: "function";
1941
2003
  readonly update: "options";
1942
2004
  };
2005
+ readonly rowKey: {
2006
+ readonly kind: "unknown";
2007
+ readonly update: "options";
2008
+ };
1943
2009
  readonly rowHeight: {
1944
2010
  readonly kind: "number";
1945
2011
  readonly update: "options";
@@ -1956,6 +2022,10 @@ declare const GRID_OPTION_META: {
1956
2022
  readonly kind: "string";
1957
2023
  readonly update: "options";
1958
2024
  };
2025
+ readonly domLayout: {
2026
+ readonly kind: "string";
2027
+ readonly update: "options";
2028
+ };
1959
2029
  readonly rowSelection: {
1960
2030
  readonly kind: "string";
1961
2031
  readonly update: "options";
@@ -2036,6 +2106,18 @@ declare const GRID_OPTION_META: {
2036
2106
  readonly kind: "object";
2037
2107
  readonly update: "options";
2038
2108
  };
2109
+ readonly stateKey: {
2110
+ readonly kind: "string";
2111
+ readonly update: "options";
2112
+ };
2113
+ readonly stateStore: {
2114
+ readonly kind: "object";
2115
+ readonly update: "options";
2116
+ };
2117
+ readonly stateSaveDebounceMs: {
2118
+ readonly kind: "number";
2119
+ readonly update: "options";
2120
+ };
2039
2121
  readonly locale: {
2040
2122
  readonly kind: "object";
2041
2123
  readonly update: "options";
@@ -2224,6 +2306,10 @@ declare const GRID_OPTION_META: {
2224
2306
  readonly kind: "boolean";
2225
2307
  readonly update: "options";
2226
2308
  };
2309
+ readonly error: {
2310
+ readonly kind: "unknown";
2311
+ readonly update: "options";
2312
+ };
2227
2313
  readonly overlayNoRowsTemplate: {
2228
2314
  readonly kind: "unknown";
2229
2315
  readonly update: "options";
@@ -2232,6 +2318,10 @@ declare const GRID_OPTION_META: {
2232
2318
  readonly kind: "unknown";
2233
2319
  readonly update: "options";
2234
2320
  };
2321
+ readonly overlayErrorTemplate: {
2322
+ readonly kind: "unknown";
2323
+ readonly update: "options";
2324
+ };
2235
2325
  readonly allowUnsafeOverlayHtml: {
2236
2326
  readonly kind: "boolean";
2237
2327
  readonly update: "options";
@@ -2332,6 +2422,28 @@ declare function saveColumnState(key: string, state: ColumnState[]): void;
2332
2422
  declare function loadColumnState(key: string): ColumnState[] | null;
2333
2423
  declare function clearColumnState(key: string): void;
2334
2424
 
2425
+ interface StoredGridState {
2426
+ schemaVersion: 1;
2427
+ savedAt: number;
2428
+ state: GridState;
2429
+ }
2430
+ interface LocalGridStateStoreOptions {
2431
+ namespace?: string;
2432
+ storage?: ColumnStateStorage;
2433
+ /** Reject unexpectedly large or corrupted payloads. Defaults to 512 KiB. */
2434
+ maxBytes?: number;
2435
+ onError?(error: unknown, operation: "load" | "save" | "clear", key: string): void;
2436
+ }
2437
+ interface ManagedGridStateStore extends GridStateStore {
2438
+ clear(key: string): void;
2439
+ storageKey(key: string): string;
2440
+ }
2441
+ /** Safe, versioned localStorage adapter for full grid state. */
2442
+ declare function createLocalGridStateStore(options?: LocalGridStateStoreOptions): ManagedGridStateStore;
2443
+ declare function saveGridState(key: string, state: GridState): void;
2444
+ declare function loadGridState(key: string): GridState | null;
2445
+ declare function clearGridState(key: string): void;
2446
+
2335
2447
  type AggValues = Record<string, any>;
2336
2448
  type AggFunction = (values: any[]) => any;
2337
2449
  declare const BUILTIN_AGG_FUNCS: Record<string, AggFunction>;
@@ -2345,6 +2457,29 @@ declare function parseDelimited(text: string, separator: string): string[][];
2345
2457
  declare function escapeHtml(value: any): string;
2346
2458
  declare function downloadFile(filename: string, content: string, mime?: string): boolean;
2347
2459
 
2460
+ interface MachTableCommandOptions<TData = any> {
2461
+ getApi(): GridApi<TData> | null;
2462
+ /** Overrides refresh for remote-query workflows. */
2463
+ reload?: () => void | Promise<void>;
2464
+ /** Fullscreen target. Defaults to the grid root's parent when available. */
2465
+ getFullscreenElement?: () => HTMLElement | null;
2466
+ }
2467
+ interface MachTableCommands {
2468
+ search(text: string | null | undefined): void;
2469
+ refresh(): Promise<void>;
2470
+ openColumns(anchor?: HTMLElement): void;
2471
+ setDensity(size: GridSize): void;
2472
+ resetColumns(): void;
2473
+ undo(): boolean;
2474
+ redo(): boolean;
2475
+ canUndo(): boolean;
2476
+ canRedo(): boolean;
2477
+ exportCsv(filename?: string): boolean;
2478
+ toggleFullscreen(): Promise<boolean>;
2479
+ }
2480
+ /** Framework-neutral command surface used by Vue/React controllers and toolbars. */
2481
+ declare function createMachTableCommands<TData = any>(options: MachTableCommandOptions<TData>): MachTableCommands;
2482
+
2348
2483
  declare function sanitizeFormulaCell(value: any): any;
2349
2484
 
2350
2485
  declare function registerCellRenderer(name: string, renderer: CellRendererFn): () => void;
@@ -2367,12 +2502,26 @@ interface ProgressConfig {
2367
2502
  }
2368
2503
  declare function createProgressBarRenderer(config?: ProgressConfig): CellRendererFn;
2369
2504
  declare function linkRenderer(params: CellRendererParams): string | HTMLElement;
2505
+ declare const ICON_PATHS: {
2506
+ readonly edit: "<path d=\"M11.5 2.5l2 2L5 13H3v-2l8.5-8.5z\"/>";
2507
+ readonly delete: "<path d=\"M3 5h10M6 5V3h4v2M5 5l.7 8h4.6L11 5\"/>";
2508
+ 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\"/>";
2509
+ readonly copy: "<rect x=\"5\" y=\"5\" width=\"8\" height=\"8\" rx=\"1\"/><path d=\"M3 11V3h8\"/>";
2510
+ readonly download: "<path d=\"M8 2v8m0 0l-3-3m3 3l3-3M2.5 13.5h11\"/>";
2511
+ 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\"/>";
2512
+ readonly close: "<path d=\"M3.5 3.5l9 9m0-9l-9 9\"/>";
2513
+ readonly check: "<path d=\"M2.5 8.5l3.5 3.5 7.5-8\"/>";
2514
+ readonly plus: "<path d=\"M8 2.5v11M2.5 8h11\"/>";
2515
+ readonly search: "<circle cx=\"7\" cy=\"7\" r=\"4.5\"/><path d=\"M10.5 10.5L14 14\"/>";
2516
+ 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\"/>";
2517
+ };
2518
+ type BuiltInActionIcon = keyof typeof ICON_PATHS;
2370
2519
  type ActionVariant = "default" | "primary" | "warning" | "success" | "danger";
2371
2520
  type ActionOverflowMode = "menu" | "drawer" | "inline";
2372
2521
  interface ActionItem<TData = any> {
2373
2522
  /** Stable identifier used by permission, telemetry and error policies. */
2374
2523
  id?: string;
2375
- icon?: string;
2524
+ icon?: BuiltInActionIcon;
2376
2525
  label?: string;
2377
2526
  title?: string;
2378
2527
  /** Backwards-compatible shorthand for variant="danger". */
@@ -2398,10 +2547,12 @@ interface ActionButtonsConfig<TData = any> {
2398
2547
  interface RowActionsConfig<TData = any> extends Omit<ActionButtonsConfig<TData>, "actions"> {
2399
2548
  onView?: (params: CellRendererParams<TData>) => unknown | Promise<unknown>;
2400
2549
  onDelete?: (params: CellRendererParams<TData>) => unknown | Promise<unknown>;
2550
+ /** Persists the just-validated row. Failures reopen row editing and keep the change dirty. */
2551
+ onSave?: (params: CellRendererParams<TData>, changes: readonly GridChange<TData>[]) => unknown | Promise<unknown>;
2401
2552
  /** Set false when this table has no full-row edit workflow. */
2402
2553
  edit?: boolean;
2403
2554
  extraActions?: ActionItem<TData>[];
2404
- labels?: Partial<Record<"view" | "edit" | "delete" | "save" | "cancel", string>>;
2555
+ labels?: Partial<Record<"view" | "edit" | "delete" | "confirm" | "save" | "cancel", string>>;
2405
2556
  permissions?: Partial<Record<"view" | "edit" | "delete", string | readonly string[]>>;
2406
2557
  /** Defaults to the translated delete label when true. */
2407
2558
  confirmDelete?: boolean | string | ((params: CellRendererParams<TData>) => boolean | string | Promise<boolean | string>);
@@ -2422,20 +2573,6 @@ declare function rowActionsColumn<TData = any>(config?: RowActionsConfig<TData>
2422
2573
  pinned?: "left" | "right";
2423
2574
  }): ColDef<TData>;
2424
2575
 
2425
- type Callable = (...args: never[]) => unknown;
2426
- type Primitive = string | number | boolean | bigint | symbol | null | undefined | Date | Callable;
2427
- type Depth = 0 | 1 | 2 | 3 | 4;
2428
- type Previous = {
2429
- 0: 0;
2430
- 1: 0;
2431
- 2: 1;
2432
- 3: 2;
2433
- 4: 3;
2434
- };
2435
- type FieldPath<T, D extends Depth = 4> = D extends 0 ? never : T extends Primitive ? never : {
2436
- [K in keyof T & string]: NonNullable<T[K]> extends Primitive | readonly unknown[] ? K : K | `${K}.${FieldPath<NonNullable<T[K]>, Previous[D]>}`;
2437
- }[keyof T & string];
2438
- 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;
2439
2576
  interface ColumnHelper<TData> {
2440
2577
  accessor<TPath extends FieldPath<TData>>(field: TPath, definition?: Omit<ColDef<TData, FieldPathValue<TData, TPath>>, "field">): ColDef<TData, FieldPathValue<TData, TPath>>;
2441
2578
  display<TValue = unknown>(definition: Omit<ColDef<TData, TValue>, "field"> & Required<Pick<ColDef<TData, TValue>, "colId">>): ColDef<TData, TValue>;
@@ -2455,6 +2592,51 @@ declare function defineMachTablePreset<TData>(preset: Partial<GridOptions<TData>
2455
2592
  /** Compile-time helper for reusable, typed grid option objects. */
2456
2593
  declare function defineGridOptions<TData>(options: GridOptions<TData>): GridOptions<TData>;
2457
2594
 
2595
+ type MachTablePresetSelection = string | readonly string[] | false | null;
2596
+ interface MachTableConfigWarning {
2597
+ code: "UNKNOWN_PRESET";
2598
+ message: string;
2599
+ preset?: string;
2600
+ }
2601
+ interface MachTableRuntimeConfig {
2602
+ /** Defaults inherited by every table in this application or subtree. */
2603
+ defaults?: Partial<GridOptions<any>>;
2604
+ /** Application-wide semantic column types. Kept separate for config readability. */
2605
+ columnTypes?: Readonly<Record<string, Partial<ColDef<any>>>>;
2606
+ /** Application-wide renderer/editor registry. Per-table components can override it. */
2607
+ components?: GridComponents;
2608
+ /** Named, reusable behavior profiles such as `list`, `crud` or `picker`. */
2609
+ presets?: Readonly<Record<string, Partial<GridOptions<any>>>>;
2610
+ /** Preset used when a table does not declare its own preset. Set false to disable. */
2611
+ defaultPreset?: MachTablePresetSelection;
2612
+ onConfigWarning?: (warning: MachTableConfigWarning) => void;
2613
+ }
2614
+ interface ResolvedMachTableConfig {
2615
+ readonly defaults: Partial<GridOptions<any>>;
2616
+ readonly presets: Readonly<Record<string, Partial<GridOptions<any>>>>;
2617
+ readonly defaultPreset: MachTablePresetSelection;
2618
+ readonly onConfigWarning?: (warning: MachTableConfigWarning) => void;
2619
+ }
2620
+ interface MachTableOptionExplanation {
2621
+ readonly key: keyof GridOptions<any> | string;
2622
+ readonly value: unknown;
2623
+ readonly source: string;
2624
+ readonly layers: readonly {
2625
+ name: string;
2626
+ value: unknown;
2627
+ }[];
2628
+ }
2629
+ interface ResolvedMachTableGridOptions<TData = any> {
2630
+ readonly options: GridOptions<TData>;
2631
+ explain(key: keyof GridOptions<TData> | string): MachTableOptionExplanation;
2632
+ }
2633
+ /** Type-checks a dedicated `mach-table.config.ts` without runtime work. */
2634
+ declare function defineMachTableConfig<const TConfig extends MachTableRuntimeConfig>(config: TConfig): TConfig;
2635
+ declare function normalizeMachTableConfig(config?: MachTableRuntimeConfig): ResolvedMachTableConfig;
2636
+ /** Merges app, route and layout configuration while preserving named presets. */
2637
+ declare function mergeMachTableConfig(parent: ResolvedMachTableConfig, child: MachTableRuntimeConfig): ResolvedMachTableConfig;
2638
+ declare function resolveMachTableGridOptions<TData>(config: ResolvedMachTableConfig, requestedPreset: MachTablePresetSelection | undefined, explicit: Partial<GridOptions<TData>>, reportWarning?: (warning: MachTableConfigWarning) => void): ResolvedMachTableGridOptions<TData>;
2639
+
2458
2640
  type BusinessColumnType = "text" | "number" | "integer" | "money" | "percent" | "percentage" | "date" | "datetime" | "boolean" | "status" | "link";
2459
2641
  interface BusinessColumnTypeOptions {
2460
2642
  locale?: string | readonly string[];
@@ -2509,4 +2691,4 @@ declare function sortNodes<TData>(nodes: RowNode<TData>[], sortModel: SortModel,
2509
2691
 
2510
2692
  declare const version: string;
2511
2693
 
2512
- 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 };
2694
+ 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 };