@gp-grid/core 0.22.0 → 0.23.1

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.ts CHANGED
@@ -331,8 +331,6 @@ interface TextFilterCondition {
331
331
  selectedValues?: Set<CellValue>;
332
332
  /** Include blank values */
333
333
  includeBlank?: boolean;
334
- /** Operator connecting this condition to the next. Defaults to ColumnFilterModel.combination */
335
- nextOperator?: FilterCombination;
336
334
  }
337
335
  /** Number filter condition */
338
336
  interface NumberFilterCondition {
@@ -341,8 +339,6 @@ interface NumberFilterCondition {
341
339
  value?: number;
342
340
  /** Second value for "between" operator */
343
341
  valueTo?: number;
344
- /** Operator connecting this condition to the next. Defaults to ColumnFilterModel.combination */
345
- nextOperator?: FilterCombination;
346
342
  }
347
343
  /** Date filter condition */
348
344
  interface DateFilterCondition {
@@ -351,16 +347,34 @@ interface DateFilterCondition {
351
347
  value?: Date | string;
352
348
  /** Second value for "between" operator */
353
349
  valueTo?: Date | string;
354
- /** Operator connecting this condition to the next. Defaults to ColumnFilterModel.combination */
355
- nextOperator?: FilterCombination;
356
350
  }
357
351
  /** Union of filter condition types */
358
352
  type FilterCondition = TextFilterCondition | NumberFilterCondition | DateFilterCondition;
359
- /** Column filter model with multiple conditions */
360
- interface ColumnFilterModel {
353
+ /** A visibly grouped set of conditions joined by one operator. */
354
+ interface FilterConditionGroup {
361
355
  conditions: FilterCondition[];
362
356
  combination: FilterCombination;
363
357
  }
358
+ /** Column filter model with one explicit level of condition groups. */
359
+ interface ColumnFilterModel {
360
+ groups: FilterConditionGroup[];
361
+ combination: FilterCombination;
362
+ }
363
+ /**
364
+ * Condition shape accepted when restoring a filter created before grouped
365
+ * composition was introduced.
366
+ */
367
+ type LegacyFilterCondition = FilterCondition & {
368
+ /** Operator connecting this condition to the next. */
369
+ nextOperator?: FilterCombination;
370
+ };
371
+ /** Legacy left-to-right column filter model accepted as migration input. */
372
+ interface LegacyColumnFilterModel {
373
+ conditions: LegacyFilterCondition[];
374
+ combination: FilterCombination;
375
+ }
376
+ /** Canonical or legacy input accepted by the imperative filter API. */
377
+ type ColumnFilterInput = ColumnFilterModel | LegacyColumnFilterModel;
364
378
  /** Filter model type - maps column ID to filter */
365
379
  type FilterModel = Record<string, ColumnFilterModel>;
366
380
  //#endregion
@@ -577,102 +591,11 @@ interface DataErrorInstruction {
577
591
  type: "DATA_ERROR";
578
592
  error: string;
579
593
  }
580
- /** Rows added instruction */
581
- interface RowsAddedInstruction {
582
- type: "ROWS_ADDED";
583
- indices: number[];
584
- count: number;
585
- totalRows: number;
586
- }
587
- /** Rows removed instruction */
588
- interface RowsRemovedInstruction {
589
- type: "ROWS_REMOVED";
590
- indices: number[];
591
- totalRows: number;
592
- }
593
- /** Rows updated instruction */
594
- interface RowsUpdatedInstruction {
595
- type: "ROWS_UPDATED";
596
- indices: number[];
597
- }
598
- /** Transaction processed instruction */
599
- interface TransactionProcessedInstruction {
600
- type: "TRANSACTION_PROCESSED";
601
- added: number;
602
- removed: number;
603
- updated: number;
604
- }
605
594
  /** Columns changed (after resize, reorder, etc.) */
606
595
  interface ColumnsChangedInstruction {
607
596
  type: "COLUMNS_CHANGED";
608
597
  columns: ColumnDefinition[];
609
598
  }
610
- /** Column resize started */
611
- interface StartColumnResizeInstruction {
612
- type: "START_COLUMN_RESIZE";
613
- colIndex: number;
614
- initialWidth: number;
615
- }
616
- /** Column resize in progress */
617
- interface UpdateColumnResizeInstruction {
618
- type: "UPDATE_COLUMN_RESIZE";
619
- colIndex: number;
620
- currentWidth: number;
621
- }
622
- /** Column resize committed */
623
- interface CommitColumnResizeInstruction {
624
- type: "COMMIT_COLUMN_RESIZE";
625
- colIndex: number;
626
- newWidth: number;
627
- }
628
- /** Column resize cancelled */
629
- interface CancelColumnResizeInstruction {
630
- type: "CANCEL_COLUMN_RESIZE";
631
- }
632
- /** Column move started */
633
- interface StartColumnMoveInstruction {
634
- type: "START_COLUMN_MOVE";
635
- sourceColIndex: number;
636
- }
637
- /** Column move position updated */
638
- interface UpdateColumnMoveInstruction {
639
- type: "UPDATE_COLUMN_MOVE";
640
- currentX: number;
641
- currentY: number;
642
- dropTargetIndex: number | null;
643
- }
644
- /** Column move committed */
645
- interface CommitColumnMoveInstruction {
646
- type: "COMMIT_COLUMN_MOVE";
647
- sourceColIndex: number;
648
- targetColIndex: number;
649
- }
650
- /** Column move cancelled */
651
- interface CancelColumnMoveInstruction {
652
- type: "CANCEL_COLUMN_MOVE";
653
- }
654
- /** Row drag started */
655
- interface StartRowDragInstruction {
656
- type: "START_ROW_DRAG";
657
- sourceRowIndex: number;
658
- }
659
- /** Row drag position updated */
660
- interface UpdateRowDragInstruction {
661
- type: "UPDATE_ROW_DRAG";
662
- currentX: number;
663
- currentY: number;
664
- dropTargetIndex: number | null;
665
- }
666
- /** Row drag committed */
667
- interface CommitRowDragInstruction {
668
- type: "COMMIT_ROW_DRAG";
669
- sourceRowIndex: number;
670
- targetRowIndex: number;
671
- }
672
- /** Row drag cancelled */
673
- interface CancelRowDragInstruction {
674
- type: "CANCEL_ROW_DRAG";
675
- }
676
599
  /** Union type of all instructions */
677
600
  type GridInstruction =
678
601
  /** Slot lifecycle */
@@ -695,16 +618,8 @@ OpenFilterPopupInstruction | CloseFilterPopupInstruction |
695
618
  StartFillInstruction | UpdateFillInstruction | CommitFillInstruction | CancelFillInstruction |
696
619
  /** Data */
697
620
  DataLoadingInstruction | DataLoadedInstruction | DataErrorInstruction |
698
- /** Transactions */
699
- RowsAddedInstruction | RowsRemovedInstruction | RowsUpdatedInstruction | TransactionProcessedInstruction |
700
621
  /** Column changes */
701
- ColumnsChangedInstruction |
702
- /** Column resize */
703
- StartColumnResizeInstruction | UpdateColumnResizeInstruction | CommitColumnResizeInstruction | CancelColumnResizeInstruction |
704
- /** Column move */
705
- StartColumnMoveInstruction | UpdateColumnMoveInstruction | CommitColumnMoveInstruction | CancelColumnMoveInstruction |
706
- /** Row drag */
707
- StartRowDragInstruction | UpdateRowDragInstruction | CommitRowDragInstruction | CancelRowDragInstruction;
622
+ ColumnsChangedInstruction;
708
623
  /** Instruction listener: Single instruction Listener that receives a single instruction, used by frameworks to update their state */
709
624
  type InstructionListener = (instruction: GridInstruction) => void;
710
625
  /** Batch instruction listener: Batch instruction Listener that receives an array of instructions, used by frameworks to update their state */
@@ -757,8 +672,6 @@ interface GridCoreOptions<TData = unknown> {
757
672
  rowLoading?: RowLoadingOptions;
758
673
  /** Enable/disable sorting globally. Default: true */
759
674
  sortingEnabled?: boolean;
760
- /** Debounce time for transactions in ms. Default 50. Set to 0 for sync. */
761
- transactionDebounceMs?: number;
762
675
  /** Function to extract unique ID from row. Required for mutations. */
763
676
  getRowId?: (row: TData) => RowId;
764
677
  /** Row/column/cell highlighting configuration */
@@ -1079,17 +992,11 @@ declare class ColumnResizeDrag<TData = unknown> {
1079
992
  //#endregion
1080
993
  //#region src/input/column-move-drag.d.ts
1081
994
  declare class ColumnMoveDrag<TData = unknown> {
1082
- private active;
995
+ private readonly gesture;
1083
996
  private sourceColIndex;
1084
- private startX;
1085
- private startY;
1086
- private thresholdMet;
1087
997
  private shiftKey;
1088
998
  private ghostWidth;
1089
999
  private ghostHeight;
1090
- private currentX;
1091
- private currentY;
1092
- private dropTargetIndex;
1093
1000
  private readonly core;
1094
1001
  private deps;
1095
1002
  constructor(core: GridCore<TData>, deps: InputHandlerDeps);
@@ -1107,14 +1014,8 @@ declare class ColumnMoveDrag<TData = unknown> {
1107
1014
  //#endregion
1108
1015
  //#region src/input/row-drag.d.ts
1109
1016
  declare class RowDrag<TData = unknown> {
1110
- private active;
1017
+ private readonly gesture;
1111
1018
  private sourceRowIndex;
1112
- private startX;
1113
- private startY;
1114
- private thresholdMet;
1115
- private currentX;
1116
- private currentY;
1117
- private dropTargetIndex;
1118
1019
  private readonly core;
1119
1020
  private deps;
1120
1021
  constructor(core: GridCore<TData>, deps: InputHandlerDeps);
@@ -1300,199 +1201,6 @@ declare class HighlightManager<TData = Record<string, unknown>> {
1300
1201
  destroy(): void;
1301
1202
  }
1302
1203
  //#endregion
1303
- //#region src/managers/row-mutation-manager.d.ts
1304
- interface RowMutationManagerOptions<TData> {
1305
- /** Get the cached rows map */
1306
- getCachedRows: () => Map<number, TData>;
1307
- /** Set the cached rows map (for bulk operations) */
1308
- setCachedRows: (rows: Map<number, TData>) => void;
1309
- /** Get total row count */
1310
- getTotalRows: () => number;
1311
- /** Set total row count */
1312
- setTotalRows: (count: number) => void;
1313
- /** Update a single slot after row change */
1314
- updateSlot: (rowIndex: number) => void;
1315
- /** Refresh all slots after bulk changes */
1316
- refreshAllSlots: () => void;
1317
- /** Emit content size change */
1318
- emitContentSize: () => void;
1319
- /** Clear selection if it references invalid rows */
1320
- clearSelectionIfInvalid: (maxValidRow: number) => void;
1321
- }
1322
- /**
1323
- * Manages row CRUD operations and cache management.
1324
- */
1325
- declare class RowMutationManager<TData = unknown> {
1326
- private readonly options;
1327
- private readonly emitter;
1328
- onInstruction: (listener: InstructionListener) => () => void;
1329
- private readonly emit;
1330
- constructor(options: RowMutationManagerOptions<TData>);
1331
- /**
1332
- * Get a row by index.
1333
- */
1334
- getRow(index: number): TData | undefined;
1335
- /**
1336
- * Add rows to the grid at the specified index.
1337
- * If no index is provided, rows are added at the end.
1338
- */
1339
- addRows(rows: TData[], index?: number): void;
1340
- /**
1341
- * Update existing rows with partial data.
1342
- */
1343
- updateRows(updates: Array<{
1344
- index: number;
1345
- data: Partial<TData>;
1346
- }>): void;
1347
- /**
1348
- * Delete rows at the specified indices.
1349
- */
1350
- deleteRows(indices: number[]): void;
1351
- /**
1352
- * Set a complete row at the specified index.
1353
- * Use this for complete row replacement. For partial updates, use updateRows.
1354
- */
1355
- setRow(index: number, data: TData): void;
1356
- destroy(): void;
1357
- }
1358
- //#endregion
1359
- //#region src/managers/instruction-batcher.d.ts
1360
- declare class InstructionBatcher {
1361
- private listeners;
1362
- private buffer;
1363
- /**
1364
- * Subscribe to batched instructions. Returns an unsubscribe function.
1365
- * Batch listeners receive arrays of instructions instead of individual ones.
1366
- */
1367
- subscribe(listener: BatchInstructionListener): () => void;
1368
- /**
1369
- * Begin buffering. `emit`/`emitBatch` accumulate into an internal buffer
1370
- * until `flush()` is called. Supports nested semantics at the caller's
1371
- * level (first startBatch "wins"; nested calls are no-ops by design).
1372
- */
1373
- start(): void;
1374
- /** Flush buffered instructions to listeners as one batch and stop buffering. */
1375
- flush(): void;
1376
- emit(instruction: GridInstruction): void;
1377
- emitBatch(instructions: GridInstruction[]): void;
1378
- clearListeners(): void;
1379
- private notify;
1380
- }
1381
- //#endregion
1382
- //#region src/managers/row-data-manager.d.ts
1383
- interface RowDataManagerOptions<TData> {
1384
- dataSource: DataSource<TData>;
1385
- rowLoading: RowLoadingOptions | undefined;
1386
- batcher: InstructionBatcher;
1387
- getColumns: () => ColumnDefinition[];
1388
- getSortModel: () => SortModel[];
1389
- getFilterModel: () => FilterModel;
1390
- getRowHeight: () => number;
1391
- getOverscan: () => number;
1392
- getScrollTop: () => number;
1393
- getViewportHeight: () => number;
1394
- onCellValueChanged?: (event: CellValueChangedEvent<TData>) => void;
1395
- getRowId?: (row: TData) => RowId;
1396
- syncSlots: () => void;
1397
- emitVisibleRange: () => void;
1398
- emitContentSize: () => void;
1399
- }
1400
- declare class RowDataManager<TData = unknown> {
1401
- private dataSource;
1402
- private readonly options;
1403
- private readonly rowLoading;
1404
- private readonly rowWindowLoader;
1405
- private cachedRows;
1406
- private totalRows;
1407
- private isDataLoading;
1408
- constructor(options: RowDataManagerOptions<TData>);
1409
- getCachedRows(): Map<number, TData>;
1410
- setCachedRows(rows: Map<number, TData>): void;
1411
- getTotalRows(): number;
1412
- setTotalRows(count: number): void;
1413
- getDataSource(): DataSource<TData>;
1414
- getRowData(rowIndex: number): TData | undefined;
1415
- isLoading(): boolean;
1416
- getCellValue(row: number, col: number): CellValue;
1417
- setCellValue(row: number, col: number, value: CellValue): void;
1418
- loadInitial(): Promise<void>;
1419
- requestVisibleRows(): void;
1420
- refreshFromTransaction(): Promise<void>;
1421
- setDataSource(dataSource: DataSource<TData>): void;
1422
- destroy(): void;
1423
- private fetchAllData;
1424
- private fetchPaginatedData;
1425
- private emitDataError;
1426
- private isPaginatedLoading;
1427
- private getInitialPaginatedRange;
1428
- private getPaginatedLoadRange;
1429
- }
1430
- //#endregion
1431
- //#region src/managers/scroll-virtualization-manager.d.ts
1432
- interface ScrollVirtualizationManagerOptions {
1433
- getRowHeight: () => number;
1434
- getHeaderHeight: () => number;
1435
- getTotalRows: () => number;
1436
- getScrollTop: () => number;
1437
- getViewportHeight: () => number;
1438
- }
1439
- declare class ScrollVirtualizationManager {
1440
- private naturalContentHeight;
1441
- private virtualContentHeight;
1442
- private scrollRatio;
1443
- private readonly options;
1444
- constructor(options: ScrollVirtualizationManagerOptions);
1445
- /**
1446
- * Update scroll virtualization state based on current row count.
1447
- * Should be called whenever totalRows changes.
1448
- */
1449
- updateContentSize(): {
1450
- naturalHeight: number;
1451
- virtualHeight: number;
1452
- scrollRatio: number;
1453
- };
1454
- /**
1455
- * Check if scroll scaling is active (large datasets exceeding browser scroll limits).
1456
- * When scaling is active, scrollRatio < 1 and scroll positions are compressed.
1457
- */
1458
- isScalingActive(): boolean;
1459
- /**
1460
- * Get the natural (uncapped) content height.
1461
- * Useful for debugging or displaying actual content size.
1462
- */
1463
- getNaturalHeight(): number;
1464
- /**
1465
- * Get the virtual (capped) content height for DOM use.
1466
- */
1467
- getVirtualHeight(): number;
1468
- /**
1469
- * Get the scroll ratio used for scroll virtualization.
1470
- * Returns 1 when no virtualization is needed, < 1 when content exceeds browser limits.
1471
- */
1472
- getScrollRatio(): number;
1473
- /**
1474
- * Get the visible row range (excluding overscan).
1475
- * Returns the first and last row indices that are actually visible in the viewport.
1476
- * Includes partially visible rows to avoid false positives when clicking on edge rows.
1477
- */
1478
- getVisibleRowRange(): {
1479
- start: number;
1480
- end: number;
1481
- };
1482
- /**
1483
- * Get the scroll position needed to bring a row into view.
1484
- * Accounts for scroll scaling when active.
1485
- */
1486
- getScrollTopForRow(rowIndex: number): number;
1487
- /**
1488
- * Get the row index at a given viewport Y position.
1489
- * Accounts for scroll scaling when active.
1490
- * @param viewportY Y position in viewport (physical pixels below header, NOT including scroll)
1491
- * @param virtualScrollTop Current scroll position from container.scrollTop (virtual/scaled)
1492
- */
1493
- getRowIndexAtDisplayY(viewportY: number, virtualScrollTop: number): number;
1494
- }
1495
- //#endregion
1496
1204
  //#region src/managers/sort-filter-manager.d.ts
1497
1205
  interface SortFilterManagerOptions<TData> {
1498
1206
  /** Get all columns */
@@ -1523,7 +1231,7 @@ declare class SortFilterManager<TData = Record<string, unknown>> {
1523
1231
  constructor(options: SortFilterManagerOptions<TData>);
1524
1232
  setSort(colId: string, direction: SortDirection | null, addToExisting?: boolean): Promise<void>;
1525
1233
  getSortModel(): SortModel[];
1526
- setFilter(colId: string, filter: ColumnFilterModel | string | null): Promise<void>;
1234
+ setFilter(colId: string, filter: ColumnFilterInput | string | null): Promise<void>;
1527
1235
  /**
1528
1236
  * Lint for hand-constructed filter models: values-mode `selectedValues`
1529
1237
  * match by strict raw identity (`"5"` never matches `5`, an ISO string
@@ -1620,189 +1328,48 @@ interface IndexedDataStoreOptions<TData> {
1620
1328
  getRowId: (row: TData) => RowId;
1621
1329
  /** Custom field accessor for nested properties */
1622
1330
  getFieldValue?: (row: TData, field: string) => CellValue;
1623
- /**
1624
- * Lookup for a field's valueFormatter. Lets free-text filter conditions
1625
- * compare against the displayed (formatted) value. Values-mode
1626
- * `selectedValues` compare raw values and never use it.
1627
- */
1628
- getValueFormatter?: (field: string) => ((v: CellValue) => string) | undefined;
1629
- }
1630
- /** Hash cache for a single row */
1631
- interface RowSortCache {
1632
- /** Map: sortModelHash -> computed hashes for that sort configuration */
1633
- hashes: Map<string, number[]>;
1634
1331
  }
1635
1332
  /**
1636
- * Efficient data structure for incremental operations on grid data.
1637
- * Supports:
1638
- * - O(1) lookup by row ID
1639
- * - O(log n) binary insertion to maintain sort order
1640
- * - Filter state caching with distinct values
1641
- * - Hash caching for fast sorted comparisons
1333
+ * Row registry backing the mutable client data source.
1334
+ *
1335
+ * Holds rows in insertion order with an id → index map for O(1) lookup and a
1336
+ * refcounted distinct-value index per field (for filter UIs). Sorting and
1337
+ * filtering are applied by the data source on top of `getAllRows()`.
1642
1338
  */
1643
1339
  declare class IndexedDataStore<TData = unknown> {
1644
1340
  private rows;
1645
1341
  private readonly rowById;
1646
- private sortedIndices;
1647
- private sortModel;
1648
- private sortModelHash;
1649
- private filterModel;
1650
- private filteredIndices;
1651
1342
  private readonly distinctValues;
1652
- private rowSortCache;
1653
1343
  private readonly options;
1654
1344
  constructor(options: IndexedDataStoreOptions<TData>, initialData?: TData[]);
1655
- /**
1656
- * Clear all data and internal caches.
1657
- * Used for proper memory cleanup when the store is no longer needed.
1658
- */
1345
+ /** Clear all data and internal indexes. */
1659
1346
  clear(): void;
1660
- /**
1661
- * Replace all data (used for initial load or full refresh).
1662
- */
1347
+ /** Replace all data (used for initial load or full refresh). */
1663
1348
  setData(data: TData[]): void;
1664
- /**
1665
- * Query data with sorting, filtering, and row-range slicing.
1666
- * Compatible with DataSource.query() interface.
1667
- */
1668
- query(request: DataSourceRequest): DataSourceResponse<TData>;
1669
- /**
1670
- * Get row by ID.
1671
- */
1672
1349
  getRowById(id: RowId): TData | undefined;
1673
- /**
1674
- * Get row by index.
1675
- */
1676
- getRowByIndex(index: number): TData | undefined;
1677
- /**
1678
- * Get total row count (unfiltered).
1679
- */
1680
1350
  getTotalRowCount(): number;
1681
- /**
1682
- * Get all rows as a new array.
1683
- * Used for direct data access when bypassing store's query system.
1684
- */
1351
+ /** All rows, in storage order, as a new array. */
1685
1352
  getAllRows(): TData[];
1686
- /**
1687
- * Move a row from one position to another in the raw data array.
1688
- * This reorders the underlying data; when no sort is active, the new order
1689
- * is reflected immediately on the next fetch.
1690
- */
1691
- moveRow(fromIndex: number, toIndex: number): void;
1692
- /**
1693
- * Get visible row count (after filtering).
1694
- */
1695
- getVisibleRowCount(): number;
1696
- /**
1697
- * Get distinct values for a field (for filter UI).
1698
- */
1353
+ /** Distinct values for a field (for filter UI). */
1699
1354
  getDistinctValues(field: string): CellValue[];
1700
- /**
1701
- * Add rows to the store.
1702
- * Rows are inserted at their correct sorted position.
1703
- */
1355
+ /** Append rows. Rows whose id already exists are skipped with a warning. */
1704
1356
  addRows(rows: TData[]): void;
1705
- /**
1706
- * Add a single row.
1707
- */
1708
1357
  private addRow;
1709
1358
  /**
1710
- * Remove rows by ID. Returns the number of rows actually removed (unknown
1711
- * ids are ignored).
1359
+ * Remove rows by ID in a single pass. Returns the number of rows actually
1360
+ * removed (unknown ids are ignored).
1712
1361
  */
1713
1362
  removeRows(ids: RowId[]): number;
1714
- /**
1715
- * Remove a single row by index.
1716
- */
1717
- private removeRowByIndex;
1718
- /**
1719
- * Update indices after a row removal.
1720
- */
1721
- private reindexAfterRemoval;
1722
- /**
1723
- * Update a cell value.
1724
- */
1363
+ /** Update a single field on a row, keeping the distinct-value index in sync. */
1725
1364
  updateCell(id: RowId, field: string, value: CellValue): void;
1726
- /**
1727
- * Update multiple fields on a row.
1728
- */
1365
+ /** Update multiple fields on a row. */
1729
1366
  updateRow(id: RowId, data: Partial<TData>): void;
1730
1367
  /**
1731
- * Set the sort model. Triggers full re-sort if model changed.
1732
- */
1733
- setSortModel(model: SortModel[]): void;
1734
- /**
1735
- * Get current sort model.
1736
- */
1737
- getSortModel(): SortModel[];
1738
- /**
1739
- * Set the filter model.
1740
- */
1741
- setFilterModel(model: FilterModel): void;
1742
- /**
1743
- * Get current filter model.
1744
- */
1745
- getFilterModel(): FilterModel;
1746
- /**
1747
- * Rebuild sorted indices (full re-sort).
1748
- */
1749
- private rebuildSortedIndices;
1750
- /**
1751
- * Rebuild hash cache for all rows.
1752
- */
1753
- private rebuildHashCache;
1754
- /**
1755
- * Compute and cache sort hashes for a row.
1756
- */
1757
- private computeRowHashes;
1758
- /**
1759
- * Compare two rows using cached hashes.
1760
- */
1761
- private compareRows;
1762
- /**
1763
- * Binary search for insertion position in sortedIndices.
1764
- */
1765
- private binarySearchInsertPosition;
1766
- /**
1767
- * Rebuild filtered indices.
1768
- */
1769
- private rebuildFilteredIndices;
1770
- /**
1771
- * Check if a row passes the current filter.
1772
- */
1773
- private rowPassesFilter;
1774
- /**
1775
- * Get visible indices (filtered + sorted).
1776
- */
1777
- private getVisibleIndices;
1778
- /**
1779
- * Rebuild distinct values cache for all fields.
1780
- */
1781
- private rebuildDistinctValues;
1782
- /**
1783
- * Update distinct-value refcounts when a row is added or removed.
1784
- * Skips null/undefined cell values — they never enter the filter popup.
1785
- */
1786
- private updateDistinctValuesForRow;
1787
- /**
1788
- * Update distinct-value refcounts when a cell value changes: decrement
1789
- * the old value's count (evicting it if this was the last reference)
1790
- * and increment the new value's count.
1791
- */
1792
- private updateDistinctValueForField;
1793
- /**
1794
- * Add a value (scalar or array) to the distinct-value refcount map.
1795
- * Creates the field's count map lazily. For arrays, each non-null item
1796
- * is counted individually so tag-column filters see element-level
1797
- * distinct values.
1798
- */
1799
- private addToDistinctValues;
1800
- /**
1801
- * Decrement refcount(s) for a value (scalar or array). When a count
1802
- * reaches zero the key is deleted so getDistinctValues() no longer
1803
- * returns stale values after the last holder is removed.
1368
+ * Move a row from one position to another in storage order. When no sort
1369
+ * is active the new order is reflected on the next fetch.
1804
1370
  */
1805
- private decrementDistinctValues;
1371
+ moveRow(fromIndex: number, toIndex: number): void;
1372
+ private rebuildIdIndex;
1806
1373
  }
1807
1374
  //#endregion
1808
1375
  //#region src/indexed-data-store/field-helpers.d.ts
@@ -1822,23 +1389,6 @@ declare function getFieldValue<TData>(row: TData, field: string): CellValue;
1822
1389
  */
1823
1390
  declare function setFieldValue<TData>(row: TData, field: string, value: CellValue): void;
1824
1391
  //#endregion
1825
- //#region src/indexed-data-store/sorting.d.ts
1826
- /**
1827
- * Convert a string to a sortable number using first 10 characters.
1828
- * Uses base-36 encoding (a-z = 0-25, 0-9 = 26-35).
1829
- */
1830
- declare function stringToSortableNumber(str: string): number;
1831
- /**
1832
- * Compare two cell values for sorting.
1833
- * Handles null/undefined, arrays, numbers, dates, and strings.
1834
- */
1835
- declare function compareValues(a: CellValue, b: CellValue): number;
1836
- /**
1837
- * Compute a sortable hash for a cell value.
1838
- * Used for fast comparisons in sorted indices.
1839
- */
1840
- declare function computeValueHash(value: CellValue): number;
1841
- //#endregion
1842
1392
  //#region src/filtering/index.d.ts
1843
1393
  /**
1844
1394
  * Check if two dates are on the same day.
@@ -1863,12 +1413,12 @@ declare function evaluateNumberCondition(cellValue: CellValue, condition: Number
1863
1413
  */
1864
1414
  declare function evaluateDateCondition(cellValue: CellValue, condition: DateFilterCondition): boolean;
1865
1415
  /**
1866
- * Evaluate a column filter model against a cell value.
1867
- * Uses left-to-right evaluation with per-condition operators.
1868
- * When `formatter` is provided, text conditions compare against the formatted
1869
- * display value rather than the raw string.
1416
+ * Evaluate a column filter model against a cell value. Conditions are joined
1417
+ * inside their explicit group, then groups are joined at the model level.
1418
+ * Legacy flat inputs retain their historical left-to-right truth table by
1419
+ * first normalizing to an equivalent grouped model.
1870
1420
  */
1871
- declare function evaluateColumnFilter(cellValue: CellValue, filter: ColumnFilterModel, formatter?: (v: CellValue) => string): boolean;
1421
+ declare function evaluateColumnFilter(cellValue: CellValue, filter: ColumnFilterInput, formatter?: (v: CellValue) => string): boolean;
1872
1422
  /**
1873
1423
  * Check if a row passes all filters in a filter model.
1874
1424
  * `getValueFormatter` — when provided — lets free-text condition operators
@@ -1969,18 +1519,10 @@ declare class TransactionManager<TData = unknown> {
1969
1519
  //#endregion
1970
1520
  //#region src/grid-core.d.ts
1971
1521
  declare class GridCore<TData = unknown> {
1522
+ private readonly config;
1972
1523
  private columns;
1973
- private readonly rowHeight;
1974
- private readonly headerHeight;
1975
- private readonly overscan;
1976
- private readonly maxFlingVelocity;
1977
- private readonly sortingEnabled;
1978
- private readonly getRowId?;
1979
- private readonly onCellValueChanged?;
1980
- private readonly rowDragEntireRow;
1981
- private readonly onRowDragEnd?;
1982
- private readonly onColumnResized?;
1983
- private readonly onColumnMoved?;
1524
+ private columnPositions;
1525
+ private readonly batcher;
1984
1526
  private readonly viewport;
1985
1527
  private scrollTopOverride;
1986
1528
  private readonly rowData;
@@ -1989,14 +1531,11 @@ declare class GridCore<TData = unknown> {
1989
1531
  readonly input: InputHandler<TData>;
1990
1532
  readonly highlight: HighlightManager<TData> | null;
1991
1533
  readonly sortFilter: SortFilterManager<TData>;
1992
- readonly rowMutation: RowMutationManager<TData>;
1993
1534
  private readonly slotPool;
1994
1535
  private readonly editManager;
1995
- private columnPositions;
1996
- private readonly batcher;
1997
1536
  private readonly scrollVirtualization;
1537
+ private readonly view;
1998
1538
  private isDestroyed;
1999
- private hasWarnedAboutScaledOverscan;
2000
1539
  constructor(options: GridCoreOptions<TData>);
2001
1540
  /**
2002
1541
  * Subscribe to batched instructions for efficient React/Vue state updates.
@@ -2013,9 +1552,8 @@ declare class GridCore<TData = unknown> {
2013
1552
  */
2014
1553
  setViewport(scrollTop: number, scrollLeft: number, width: number, height: number): void;
2015
1554
  setSort(colId: string, direction: SortDirection | null, addToExisting?: boolean): Promise<void>;
2016
- setFilter(colId: string, filter: ColumnFilterModel | string | null): Promise<void>;
1555
+ setFilter(colId: string, filter: ColumnFilterInput | string | null): Promise<void>;
2017
1556
  hasActiveFilter(colId: string): boolean;
2018
- getDistinctValuesForColumn(colId: string, maxValues?: number): CellValue[];
2019
1557
  /**
2020
1558
  * Open a column filter popup.
2021
1559
  * Adapters can skip distinct-value computation when their popup only uses
@@ -2053,15 +1591,7 @@ declare class GridCore<TData = unknown> {
2053
1591
  setCellValue(row: number, col: number, value: CellValue): void;
2054
1592
  private clearSelectionIfInvalid;
2055
1593
  private computeColumnPositions;
2056
- private emitContentSize;
2057
- /**
2058
- * One-time advisory when scroll virtualization kicks in with a small
2059
- * overscan: momentum flings move several rows per frame at that scale,
2060
- * and a small overscan shows blank rows behind the fling.
2061
- */
2062
- private warnIfOverscanTooLowForScaling;
2063
- private emitHeaders;
2064
- private emitVisibleRange;
1594
+ private columnOperationDeps;
2065
1595
  /**
2066
1596
  * Set the displayed width of a column and recompute layout. `width` is the
2067
1597
  * post-redistribution displayed width — the stored `column.width` is
@@ -2098,12 +1628,12 @@ declare class GridCore<TData = unknown> {
2098
1628
  * synthetic scroller while scroll virtualization is active.
2099
1629
  */
2100
1630
  getMaxFlingVelocity(): number;
2101
- getNaturalHeight(): number;
2102
1631
  getScrollRatio(): number;
2103
1632
  getVisibleRowRange(): {
2104
1633
  start: number;
2105
1634
  end: number;
2106
1635
  };
1636
+ /** Used structurally by `scrollCellIntoView` in the framework wrappers. */
2107
1637
  getScrollTopForRow(rowIndex: number): number;
2108
1638
  getRowIndexAtDisplayY(viewportY: number, virtualScrollTop: number): number;
2109
1639
  /**
@@ -2127,31 +1657,6 @@ declare class GridCore<TData = unknown> {
2127
1657
  * Useful after in-place data modifications like fill operations.
2128
1658
  */
2129
1659
  refreshSlotData(): void;
2130
- /**
2131
- * Add rows to the grid at the specified index.
2132
- * If no index is provided, rows are added at the end.
2133
- */
2134
- addRows(rows: TData[], index?: number): void;
2135
- /**
2136
- * Update existing rows with partial data.
2137
- */
2138
- updateRows(updates: Array<{
2139
- index: number;
2140
- data: Partial<TData>;
2141
- }>): void;
2142
- /**
2143
- * Delete rows at the specified indices.
2144
- */
2145
- deleteRows(indices: number[]): void;
2146
- /**
2147
- * Get a row by index.
2148
- */
2149
- getRow(index: number): TData | undefined;
2150
- /**
2151
- * Set a complete row at the specified index.
2152
- * Use this for complete row replacement. For partial updates, use updateRows.
2153
- */
2154
- setRow(index: number, data: TData): void;
2155
1660
  /**
2156
1661
  * Update the data source and refresh.
2157
1662
  * Preserves grid state (sort, filter, scroll position).
@@ -2170,31 +1675,196 @@ declare class GridCore<TData = unknown> {
2170
1675
  destroy(): void;
2171
1676
  }
2172
1677
  //#endregion
2173
- //#region src/utils/positioning.d.ts
2174
- /**
2175
- * Calculate cumulative column positions (prefix sums)
2176
- * Returns an array where positions[i] is the left position of column i
2177
- * positions[columns.length] is the total width
2178
- */
2179
- declare const calculateColumnPositions: (columns: ColumnDefinition[]) => number[];
2180
- /**
2181
- * Get total width from column positions
2182
- */
2183
- declare const getTotalWidth: (columnPositions: number[]) => number;
2184
- /**
2185
- * Calculate scaled column positions when container is wider than total column widths.
2186
- * Columns expand proportionally based on their original width ratios.
2187
- *
2188
- * @param columns - Column definitions with original widths
2189
- * @param containerWidth - Available container width
2190
- * @returns Object with positions array and widths array
2191
- */
2192
- declare const calculateScaledColumnPositions: (columns: ColumnDefinition[], containerWidth: number) => {
2193
- positions: number[];
2194
- widths: number[];
2195
- };
2196
- /**
2197
- * Find column index at a given X coordinate
1678
+ //#region src/sorting/parallel-sort-manager.d.ts
1679
+ interface ParallelSortOptions {
1680
+ /** Maximum number of workers (default: navigator.hardwareConcurrency || 4) */
1681
+ maxWorkers?: number;
1682
+ /** Threshold for parallel sorting (default: 400000) */
1683
+ parallelThreshold?: number;
1684
+ /** Minimum chunk size (default: 50000) */
1685
+ minChunkSize?: number;
1686
+ }
1687
+ //#endregion
1688
+ //#region src/data-source/client-data-source.d.ts
1689
+ interface ClientDataSourceOptions<TData> {
1690
+ /** Custom field accessor for nested properties */
1691
+ getFieldValue?: (row: TData, field: string) => CellValue;
1692
+ /**
1693
+ * Lookup for a field's valueFormatter. Lets free-text filter conditions
1694
+ * compare against the displayed (formatted) value the user typed against.
1695
+ * Values-mode `selectedValues` compare raw values and never use it.
1696
+ */
1697
+ getValueFormatter?: (field: string) => ((v: CellValue) => string) | undefined;
1698
+ /** Use Web Worker for sorting large datasets (default: true) */
1699
+ useWorker?: boolean;
1700
+ /** Options for parallel sorting (only used when useWorker is true) */
1701
+ parallelSort?: ParallelSortOptions | false;
1702
+ }
1703
+ /**
1704
+ * Creates a client-side data source that holds all data in memory.
1705
+ * Sorting and filtering are performed client-side.
1706
+ * For large datasets, sorting is automatically offloaded to a Web Worker.
1707
+ */
1708
+ declare function createClientDataSource<TData = unknown>(data: TData[], options?: ClientDataSourceOptions<TData>): DataSource<TData>;
1709
+ /**
1710
+ * Convenience function to create a data source from an array.
1711
+ * This provides backwards compatibility with the old `rowData` prop.
1712
+ */
1713
+ declare function createDataSourceFromArray<TData = unknown>(data: TData[]): DataSource<TData>;
1714
+ //#endregion
1715
+ //#region src/data-source/server-data-source.d.ts
1716
+ type ServerQueryFunction<TData> = (request: DataSourceRequest) => Promise<DataSourceResponse<TData>>;
1717
+ interface ServerDataSourceOptions {
1718
+ /** Server data sources use paginated loading by default. */
1719
+ loadMode?: DataSourceLoadMode;
1720
+ }
1721
+ /**
1722
+ * Creates a server-side data source that delegates all operations to the server.
1723
+ * The query function receives sort/filter/range params to pass to the API.
1724
+ */
1725
+ declare function createServerDataSource<TData = unknown>(queryFn: ServerQueryFunction<TData>, options?: ServerDataSourceOptions): DataSource<TData>;
1726
+ //#endregion
1727
+ //#region src/data-source/mutable-data-source.d.ts
1728
+ /** Callback for data change notifications */
1729
+ type DataChangeListener = (result: TransactionResult) => void;
1730
+ /**
1731
+ * Data source with mutation capabilities.
1732
+ * Extends DataSource with add, remove, and update operations.
1733
+ */
1734
+ interface MutableDataSource<TData = unknown> extends DataSource<TData> {
1735
+ /** Add rows to the data source. Queued and processed after debounce. */
1736
+ addRows(rows: TData[]): void;
1737
+ /** Remove rows by ID. Queued and processed after debounce. */
1738
+ removeRows(ids: RowId[]): void;
1739
+ /** Update a cell value. Queued and processed after debounce. */
1740
+ updateCell(id: RowId, field: string, value: CellValue): void;
1741
+ /** Update multiple fields on a row. Queued and processed after debounce. */
1742
+ updateRow(id: RowId, data: Partial<TData>): void;
1743
+ /** Force immediate processing of queued transactions. */
1744
+ flushTransactions(): Promise<void>;
1745
+ /** Check if there are pending transactions. */
1746
+ hasPendingTransactions(): boolean;
1747
+ /** Get distinct values for a field (for filter UI). */
1748
+ getDistinctValues(field: string): CellValue[];
1749
+ /** Get a row by ID. */
1750
+ getRowById(id: RowId): TData | undefined;
1751
+ /** Get total row count. */
1752
+ getTotalRowCount(): number;
1753
+ /** Subscribe to data change notifications. Returns unsubscribe function. */
1754
+ subscribe(listener: DataChangeListener): () => void;
1755
+ /** Clear all data from the data source. */
1756
+ clear(): void;
1757
+ /** Move a row from one display position to another. */
1758
+ moveRow(fromIndex: number, toIndex: number): void;
1759
+ }
1760
+ interface MutableClientDataSourceOptions<TData> {
1761
+ /** Function to extract unique ID from row. Required. */
1762
+ getRowId: (row: TData) => RowId;
1763
+ /** Custom field accessor for nested properties. */
1764
+ getFieldValue?: (row: TData, field: string) => CellValue;
1765
+ /**
1766
+ * Lookup for a field's valueFormatter. Lets free-text filter conditions
1767
+ * compare against the displayed (formatted) value. Values-mode
1768
+ * `selectedValues` compare raw values and never use it.
1769
+ */
1770
+ getValueFormatter?: (field: string) => ((v: CellValue) => string) | undefined;
1771
+ /** Debounce time for transactions in ms. Default 50. Set to 0 for sync. */
1772
+ debounceMs?: number;
1773
+ /** Callback when transactions are processed. */
1774
+ onTransactionProcessed?: (result: TransactionResult) => void;
1775
+ /** Use Web Worker for sorting large datasets (default: true) */
1776
+ useWorker?: boolean;
1777
+ /** Options for parallel sorting (only used when useWorker is true) */
1778
+ parallelSort?: ParallelSortOptions | false;
1779
+ }
1780
+ /**
1781
+ * Creates a mutable client-side data source with transaction support.
1782
+ * Uses IndexedDataStore for efficient incremental operations.
1783
+ * For large datasets, sorting is automatically offloaded to a Web Worker.
1784
+ */
1785
+ declare function createMutableClientDataSource<TData = unknown>(data: TData[], options: MutableClientDataSourceOptions<TData>): MutableDataSource<TData>;
1786
+ //#endregion
1787
+ //#region src/filtering/normalize.d.ts
1788
+ /** Check whether a filter still uses the legacy flat condition list. */
1789
+ declare const isLegacyColumnFilterModel: (filter: ColumnFilterInput) => filter is LegacyColumnFilterModel;
1790
+ /**
1791
+ * Convert a legacy left-to-right filter into the canonical one-level grouped
1792
+ * representation. Canonical inputs are returned unchanged.
1793
+ */
1794
+ declare const normalizeColumnFilterModel: (filter: ColumnFilterInput) => ColumnFilterModel;
1795
+ //#endregion
1796
+ //#region src/filtering/distinct-entries.d.ts
1797
+ /** One checkbox row in the values-mode filter popup. */
1798
+ interface DistinctValueEntry {
1799
+ /** Formatted display string shown next to the checkbox. */
1800
+ label: string;
1801
+ /** All raw values that format to this label. Ticking the label selects them all. */
1802
+ values: CellValue[];
1803
+ }
1804
+ /**
1805
+ * Canonical identity key for a raw cell value, used to compare values-mode
1806
+ * selections against cell values without ever consulting a formatter.
1807
+ *
1808
+ * Type-prefixed so raw `5` and raw `"5"` never collide. Arrays are sorted by
1809
+ * their elements' own keys first so element order is irrelevant (same rule as
1810
+ * the distinct-value scan). Objects rely on JSON.stringify, so key order matters
1811
+ * for them — a pre-existing limitation of distinct-value identity.
1812
+ */
1813
+ declare const rawValueKey: (value: CellValue) => string;
1814
+ /**
1815
+ * Whether a cell value counts as blank for filtering purposes: null,
1816
+ * undefined, empty string, or empty array (e.g. a tags column with no tags).
1817
+ * Blank cells are matched via `TextFilterCondition.includeBlank` — the
1818
+ * popup's "(Blanks)" checkbox — never via `selectedValues`.
1819
+ */
1820
+ declare const isBlankCellValue: (value: CellValue) => boolean;
1821
+ /**
1822
+ * Group raw distinct values by their display label.
1823
+ *
1824
+ * Multiple raw values can format to the same label; the returned entry keeps
1825
+ * every one of them so that applying the filter selects all rows rendering
1826
+ * that label. Blank values are skipped (the popup exposes them through the
1827
+ * dedicated "include blanks" checkbox), arrays are normalized to sorted
1828
+ * copies, and raws are deduplicated within a group by {@link rawValueKey}.
1829
+ */
1830
+ declare const groupDistinctValues: (values: readonly CellValue[], formatter?: (v: CellValue) => string) => DistinctValueEntry[];
1831
+ /**
1832
+ * Map a filter model's raw `selectedValues` back to the popup labels that
1833
+ * should render as ticked. A label is ticked when at least one of its raw
1834
+ * values is selected (data may have changed since the filter was applied).
1835
+ */
1836
+ declare const labelsForSelectedValues: (entries: readonly DistinctValueEntry[], selectedValues: ReadonlySet<CellValue>) => Set<string>;
1837
+ /**
1838
+ * Collect the raw values behind the ticked labels — the set to store in
1839
+ * `TextFilterCondition.selectedValues` on apply.
1840
+ */
1841
+ declare const rawValuesForLabels: (entries: readonly DistinctValueEntry[], labels: ReadonlySet<string>) => Set<CellValue>;
1842
+ //#endregion
1843
+ //#region src/utils/positioning.d.ts
1844
+ /**
1845
+ * Calculate cumulative column positions (prefix sums)
1846
+ * Returns an array where positions[i] is the left position of column i
1847
+ * positions[columns.length] is the total width
1848
+ */
1849
+ declare const calculateColumnPositions: (columns: ColumnDefinition[]) => number[];
1850
+ /**
1851
+ * Get total width from column positions
1852
+ */
1853
+ declare const getTotalWidth: (columnPositions: number[]) => number;
1854
+ /**
1855
+ * Calculate scaled column positions when container is wider than total column widths.
1856
+ * Columns expand proportionally based on their original width ratios.
1857
+ *
1858
+ * @param columns - Column definitions with original widths
1859
+ * @param containerWidth - Available container width
1860
+ * @returns Object with positions array and widths array
1861
+ */
1862
+ declare const calculateScaledColumnPositions: (columns: ColumnDefinition[], containerWidth: number) => {
1863
+ positions: number[];
1864
+ widths: number[];
1865
+ };
1866
+ /**
1867
+ * Find column index at a given X coordinate
2198
1868
  */
2199
1869
  declare const findColumnAtX: (x: number, columnPositions: number[]) => number;
2200
1870
  //#endregion
@@ -2232,20 +1902,6 @@ declare const isCellInFillPreview: (row: number, col: number, isDraggingFill: bo
2232
1902
  * Build cell CSS classes based on state
2233
1903
  */
2234
1904
  declare const buildCellClasses: (isActive: boolean, isSelected: boolean, isEditing: boolean, inFillPreview: boolean) => string;
2235
- /**
2236
- * Check if a row overlaps the selection range
2237
- */
2238
- declare const isRowInSelectionRange: (rowIndex: number, range: CellRange | null) => boolean;
2239
- /**
2240
- * Check if a column overlaps the selection range
2241
- */
2242
- declare const isColumnInSelectionRange: (colIndex: number, range: CellRange | null) => boolean;
2243
- //#endregion
2244
- //#region src/utils/event-emitter.d.ts
2245
- /**
2246
- * Batch instruction listener for efficient state updates
2247
- */
2248
- type BatchInstructionListener$1 = (instructions: GridInstruction[]) => void;
2249
1905
  //#endregion
2250
1906
  //#region src/types/ui-state.d.ts
2251
1907
  interface SlotData<TData = unknown> {
@@ -2315,11 +1971,16 @@ interface GridState<TData = unknown> {
2315
1971
  pendingScrollTop: number | null;
2316
1972
  }
2317
1973
  //#endregion
2318
- //#region src/utils/scroll-helpers.d.ts
1974
+ //#region src/state-reducer.d.ts
2319
1975
  /**
2320
- * Find the slot for a given row index
1976
+ * Apply a single instruction to mutable slot/header Maps and return
1977
+ * other state changes as a partial object.
1978
+ *
1979
+ * Returns `null` when only the Maps were mutated (no primitive field changes).
2321
1980
  */
2322
- declare const findSlotForRow: (slots: Map<string, SlotData>, rowIndex: number) => SlotData | null;
1981
+ declare const applyInstruction: <TData = unknown>(instruction: GridInstruction, slots: Map<string, SlotData<TData>>, headers: Map<number, HeaderData>) => Partial<GridState<TData>> | null;
1982
+ //#endregion
1983
+ //#region src/utils/scroll-helpers.d.ts
2323
1984
  /**
2324
1985
  * Column geometry needed to scroll a cell horizontally into view.
2325
1986
  * Columns are not scroll-virtualized, so positions map 1:1 to scrollLeft.
@@ -2427,500 +2088,6 @@ declare const calculateFilterPopupPosition: (headerCell: HTMLElement, popupEl: H
2427
2088
  */
2428
2089
  declare const bindPeekSelectAll: (overlay: HTMLElement) => (() => void);
2429
2090
  //#endregion
2430
- //#region src/slot-pool.d.ts
2431
- interface SlotPoolManagerOptions {
2432
- /** Get current row height */
2433
- getRowHeight: () => number;
2434
- /** Get current header height */
2435
- getHeaderHeight: () => number;
2436
- /** Get overscan count */
2437
- getOverscan: () => number;
2438
- /** Get current scroll top position (natural, not virtual) */
2439
- getScrollTop: () => number;
2440
- /** Get viewport height */
2441
- getViewportHeight: () => number;
2442
- /** Get total row count */
2443
- getTotalRows: () => number;
2444
- /** Get scroll ratio for virtualization (1 = no virtualization) */
2445
- getScrollRatio: () => number;
2446
- /** Get virtual content height */
2447
- getVirtualContentHeight: () => number;
2448
- /** Get row data by index */
2449
- getRowData: (rowIndex: number) => unknown;
2450
- }
2451
- /**
2452
- * Manages the slot pool for virtual scrolling.
2453
- * Handles slot creation, recycling, positioning, and destruction.
2454
- */
2455
- declare class SlotPoolManager {
2456
- private readonly state;
2457
- private readonly options;
2458
- private readonly emitter;
2459
- private isDestroyed;
2460
- onInstruction: (listener: InstructionListener) => () => void;
2461
- onBatchInstruction: (listener: BatchInstructionListener$1) => () => void;
2462
- private readonly emit;
2463
- private readonly emitBatch;
2464
- constructor(options: SlotPoolManagerOptions);
2465
- /**
2466
- * Get the slot ID for a given row index.
2467
- */
2468
- getSlotForRow(rowIndex: number): string | undefined;
2469
- /**
2470
- * Get all current slots.
2471
- */
2472
- getSlots(): Map<string, SlotState>;
2473
- /**
2474
- * Synchronize slots with current viewport position.
2475
- * This implements the slot recycling strategy.
2476
- */
2477
- syncSlots(): void;
2478
- /**
2479
- * Partition existing slots into recyclable and still-needed.
2480
- * Mutates requiredRows: rows that already have a slot are removed.
2481
- */
2482
- private partitionSlots;
2483
- /**
2484
- * Assign a row to a recycled or newly created slot.
2485
- */
2486
- private assignSlotToRow;
2487
- /**
2488
- * Push MOVE_SLOT instructions for slots whose position has drifted.
2489
- */
2490
- private updateSlotPositions;
2491
- /**
2492
- * Destroy all slots.
2493
- */
2494
- destroyAllSlots(): void;
2495
- /**
2496
- * Clean up resources for garbage collection.
2497
- * This method is idempotent - safe to call multiple times.
2498
- */
2499
- destroy(): void;
2500
- /**
2501
- * Refresh all slot data without changing which rows are displayed.
2502
- * Used after filtering/sorting when data changes.
2503
- */
2504
- refreshAllSlots(): void;
2505
- /**
2506
- * Update a single slot's data.
2507
- */
2508
- updateSlot(rowIndex: number): void;
2509
- /**
2510
- * Calculate the translateY position for a row.
2511
- * Handles scroll virtualization for very large datasets.
2512
- *
2513
- * When virtualization is active (scrollRatio < 1), we use viewport-relative
2514
- * positioning to keep translateY values small. This prevents browser rendering
2515
- * issues that occur at extreme pixel values (millions of pixels).
2516
- *
2517
- * Note: The header is rendered outside the content sizer, so row positions
2518
- * start at 0 (not headerHeight) within the rows container.
2519
- */
2520
- private getRowTranslateY;
2521
- /**
2522
- * Get the translateY position for a row inside the rows wrapper.
2523
- * Public accessor for use by input handler (e.g., drop indicator positioning).
2524
- */
2525
- getRowTranslateYForIndex(rowIndex: number): number;
2526
- /**
2527
- * Get the Y offset for the rows wrapper container.
2528
- * When virtualization is active, this positions the wrapper so rows
2529
- * with small translateY values appear at the correct scroll position.
2530
- */
2531
- getRowsWrapperOffset(): number;
2532
- }
2533
- //#endregion
2534
- //#region src/edit-manager.d.ts
2535
- interface EditManagerOptions {
2536
- /** Get column definition by index */
2537
- getColumn: (colIndex: number) => ColumnDefinition | undefined;
2538
- /** Get cell value */
2539
- getCellValue: (row: number, col: number) => CellValue;
2540
- /** Set cell value */
2541
- setCellValue: (row: number, col: number, value: CellValue) => void;
2542
- /** Callback when edit is committed (to update slot display) */
2543
- onCommit?: (row: number, col: number, value: CellValue) => void;
2544
- }
2545
- /**
2546
- * Manages cell editing state and operations.
2547
- */
2548
- declare class EditManager {
2549
- private editState;
2550
- private peekState;
2551
- private readonly options;
2552
- private readonly emitter;
2553
- onInstruction: (listener: InstructionListener) => () => void;
2554
- private readonly emit;
2555
- constructor(options: EditManagerOptions);
2556
- /**
2557
- * Get the current edit state.
2558
- */
2559
- getState(): EditState | null;
2560
- /**
2561
- * Check if currently editing.
2562
- */
2563
- isEditing(): boolean;
2564
- /**
2565
- * Check if a specific cell is being edited.
2566
- */
2567
- isEditingCell(row: number, col: number): boolean;
2568
- /**
2569
- * Start editing a cell.
2570
- * Returns true if edit was started, false if cell is not editable.
2571
- */
2572
- startEdit(row: number, col: number): boolean;
2573
- /**
2574
- * Get the cell currently shown in a peek overlay, or null.
2575
- */
2576
- getPeekState(): CellPosition | null;
2577
- /**
2578
- * Open a peek overlay on a cell. Caller is responsible for guarding on
2579
- * `column.peekable` — the manager only refuses when an edit is in progress
2580
- * (edit and peek are mutually exclusive).
2581
- * Returns true if the peek was opened.
2582
- */
2583
- startPeek(row: number, col: number): boolean;
2584
- /**
2585
- * Close any active peek overlay. No-op if none is open.
2586
- */
2587
- stopPeek(): void;
2588
- /**
2589
- * Update the current edit value.
2590
- */
2591
- updateValue(value: CellValue): void;
2592
- /**
2593
- * Commit the current edit.
2594
- * Saves the value and closes the editor.
2595
- */
2596
- commit(): void;
2597
- /**
2598
- * Cancel the current edit.
2599
- * Discards changes and closes the editor.
2600
- */
2601
- cancel(): void;
2602
- /**
2603
- * Clean up resources for garbage collection.
2604
- */
2605
- destroy(): void;
2606
- }
2607
- //#endregion
2608
- //#region src/sorting/parallel-sort-manager.d.ts
2609
- interface ParallelSortOptions {
2610
- /** Maximum number of workers (default: navigator.hardwareConcurrency || 4) */
2611
- maxWorkers?: number;
2612
- /** Threshold for parallel sorting (default: 400000) */
2613
- parallelThreshold?: number;
2614
- /** Minimum chunk size (default: 50000) */
2615
- minChunkSize?: number;
2616
- }
2617
- /**
2618
- * Manages parallel sorting operations using a worker pool.
2619
- * Automatically decides between single-worker and parallel sorting based on data size.
2620
- */
2621
- declare class ParallelSortManager {
2622
- private readonly pool;
2623
- private readonly parallelThreshold;
2624
- private readonly minChunkSize;
2625
- private isTerminated;
2626
- constructor(options?: ParallelSortOptions);
2627
- isAvailable(): boolean;
2628
- terminate(): void;
2629
- sortIndices(values: number[], direction: "asc" | "desc"): Promise<Uint32Array>;
2630
- sortStringHashes(hashChunks: Float64Array[], direction: "asc" | "desc", originalStrings: string[]): Promise<Uint32Array>;
2631
- sortMultiColumn(columns: number[][], directions: ("asc" | "desc")[]): Promise<Uint32Array>;
2632
- private assertNotTerminated;
2633
- private sortIndicesSingle;
2634
- private sortStringHashesSingle;
2635
- private sortMultiColumnSingle;
2636
- private boundariesFor;
2637
- private runChunks;
2638
- private sortIndicesParallel;
2639
- private sortStringHashesParallel;
2640
- private sortMultiColumnParallel;
2641
- }
2642
- //#endregion
2643
- //#region src/sorting/worker-pool.d.ts
2644
- interface WorkerPoolOptions {
2645
- /** Maximum number of workers (default: navigator.hardwareConcurrency ?? 4) */
2646
- maxWorkers?: number;
2647
- /** Whether to pre-warm workers on initialization */
2648
- preWarm?: boolean;
2649
- }
2650
- /**
2651
- * Manages a pool of Web Workers for parallel task execution.
2652
- * Workers are created lazily and reused across operations.
2653
- */
2654
- declare class WorkerPool {
2655
- private readonly workerCode;
2656
- private readonly maxWorkers;
2657
- private workers;
2658
- private workerUrl;
2659
- private nextRequestId;
2660
- private isTerminated;
2661
- constructor(workerCode: string, options?: WorkerPoolOptions);
2662
- /**
2663
- * Get the current pool size (number of active workers).
2664
- */
2665
- getPoolSize(): number;
2666
- /**
2667
- * Get the maximum pool size.
2668
- */
2669
- getMaxWorkers(): number;
2670
- /**
2671
- * Check if the pool is available for use.
2672
- */
2673
- isAvailable(): boolean;
2674
- /**
2675
- * Execute a single task on an available worker.
2676
- * Returns the worker's response.
2677
- */
2678
- execute<TRequest extends {
2679
- id?: number;
2680
- }, TResponse>(request: TRequest, transferables?: Transferable[]): Promise<TResponse>;
2681
- /**
2682
- * Execute multiple tasks in parallel across available workers.
2683
- * Each task is assigned to a different worker if possible.
2684
- * Returns results in the same order as the input requests.
2685
- */
2686
- executeParallel<TRequest extends {
2687
- id?: number;
2688
- }, TResponse>(tasks: Array<{
2689
- request: TRequest;
2690
- transferables?: Transferable[];
2691
- }>): Promise<TResponse[]>;
2692
- /**
2693
- * Terminate all workers and clean up resources.
2694
- */
2695
- terminate(): void;
2696
- /**
2697
- * Pre-warm workers by creating them ahead of time.
2698
- */
2699
- private preWarmWorkers;
2700
- /**
2701
- * Ensure at least `count` workers exist in the pool.
2702
- */
2703
- private ensureWorkers;
2704
- /**
2705
- * Get an available worker, creating one if needed.
2706
- */
2707
- private getAvailableWorker;
2708
- /**
2709
- * Create a new worker and add it to the pool.
2710
- */
2711
- private createWorker;
2712
- /**
2713
- * Respawn a failed worker.
2714
- */
2715
- private respawnWorker;
2716
- }
2717
- //#endregion
2718
- //#region src/sorting/k-way-merge.d.ts
2719
- /**
2720
- * Represents a sorted chunk with its values and offset in the original array.
2721
- */
2722
- interface SortedChunk {
2723
- /** Sorted indices (local to this chunk) */
2724
- indices: Uint32Array;
2725
- /** Values for comparison (in same order as indices) */
2726
- values: Float64Array;
2727
- /** Offset of this chunk in the original array */
2728
- offset: number;
2729
- }
2730
- /**
2731
- * Represents a sorted chunk for multi-column sorting.
2732
- */
2733
- interface MultiColumnSortedChunk {
2734
- /** Sorted indices (local to this chunk) */
2735
- indices: Uint32Array;
2736
- /** Values for comparison - array of columns, each in same order as indices */
2737
- columns: Float64Array[];
2738
- /** Sort directions for each column (1 = asc, -1 = desc) */
2739
- directions: Int8Array;
2740
- /** Offset of this chunk in the original array */
2741
- offset: number;
2742
- }
2743
- /**
2744
- * Merge multiple sorted chunks into a single sorted result.
2745
- * Uses a min-heap for O(n log k) time complexity.
2746
- *
2747
- * @param chunks - Array of sorted chunks to merge
2748
- * @param direction - Sort direction ('asc' or 'desc')
2749
- * @returns Uint32Array of globally sorted indices
2750
- */
2751
- declare function kWayMerge(chunks: SortedChunk[], direction: SortDirection): Uint32Array;
2752
- /**
2753
- * Merge multiple sorted chunks for multi-column sorting.
2754
- *
2755
- * @param chunks - Array of multi-column sorted chunks
2756
- * @returns Uint32Array of globally sorted indices
2757
- */
2758
- declare function kWayMergeMultiColumn(chunks: MultiColumnSortedChunk[]): Uint32Array;
2759
- /**
2760
- * Detect collision runs at chunk boundaries after merge.
2761
- * This is used for string sorting where hashes may collide across chunks.
2762
- *
2763
- * @param chunks - Original sorted chunks with their hash values
2764
- * @param _direction - Sort direction
2765
- * @returns Array of boundary collision positions [start1, end1, start2, end2, ...]
2766
- */
2767
- declare function detectBoundaryCollisions(chunks: SortedChunk[], _direction: SortDirection): Uint32Array;
2768
- //#endregion
2769
- //#region src/data-source/client-data-source.d.ts
2770
- interface ClientDataSourceOptions<TData> {
2771
- /** Custom field accessor for nested properties */
2772
- getFieldValue?: (row: TData, field: string) => CellValue;
2773
- /**
2774
- * Lookup for a field's valueFormatter. Lets free-text filter conditions
2775
- * compare against the displayed (formatted) value the user typed against.
2776
- * Values-mode `selectedValues` compare raw values and never use it.
2777
- */
2778
- getValueFormatter?: (field: string) => ((v: CellValue) => string) | undefined;
2779
- /** Use Web Worker for sorting large datasets (default: true) */
2780
- useWorker?: boolean;
2781
- /** Options for parallel sorting (only used when useWorker is true) */
2782
- parallelSort?: ParallelSortOptions | false;
2783
- }
2784
- /**
2785
- * Creates a client-side data source that holds all data in memory.
2786
- * Sorting and filtering are performed client-side.
2787
- * For large datasets, sorting is automatically offloaded to a Web Worker.
2788
- */
2789
- declare function createClientDataSource<TData = unknown>(data: TData[], options?: ClientDataSourceOptions<TData>): DataSource<TData>;
2790
- /**
2791
- * Convenience function to create a data source from an array.
2792
- * This provides backwards compatibility with the old `rowData` prop.
2793
- */
2794
- declare function createDataSourceFromArray<TData = unknown>(data: TData[]): DataSource<TData>;
2795
- //#endregion
2796
- //#region src/data-source/server-data-source.d.ts
2797
- type ServerQueryFunction<TData> = (request: DataSourceRequest) => Promise<DataSourceResponse<TData>>;
2798
- interface ServerDataSourceOptions {
2799
- /** Server data sources use paginated loading by default. */
2800
- loadMode?: DataSourceLoadMode;
2801
- }
2802
- /**
2803
- * Creates a server-side data source that delegates all operations to the server.
2804
- * The query function receives sort/filter/range params to pass to the API.
2805
- */
2806
- declare function createServerDataSource<TData = unknown>(queryFn: ServerQueryFunction<TData>, options?: ServerDataSourceOptions): DataSource<TData>;
2807
- //#endregion
2808
- //#region src/data-source/mutable-data-source.d.ts
2809
- /** Callback for data change notifications */
2810
- type DataChangeListener = (result: TransactionResult) => void;
2811
- /**
2812
- * Data source with mutation capabilities.
2813
- * Extends DataSource with add, remove, and update operations.
2814
- */
2815
- interface MutableDataSource<TData = unknown> extends DataSource<TData> {
2816
- /** Add rows to the data source. Queued and processed after debounce. */
2817
- addRows(rows: TData[]): void;
2818
- /** Remove rows by ID. Queued and processed after debounce. */
2819
- removeRows(ids: RowId[]): void;
2820
- /** Update a cell value. Queued and processed after debounce. */
2821
- updateCell(id: RowId, field: string, value: CellValue): void;
2822
- /** Update multiple fields on a row. Queued and processed after debounce. */
2823
- updateRow(id: RowId, data: Partial<TData>): void;
2824
- /** Force immediate processing of queued transactions. */
2825
- flushTransactions(): Promise<void>;
2826
- /** Check if there are pending transactions. */
2827
- hasPendingTransactions(): boolean;
2828
- /** Get distinct values for a field (for filter UI). */
2829
- getDistinctValues(field: string): CellValue[];
2830
- /** Get a row by ID. */
2831
- getRowById(id: RowId): TData | undefined;
2832
- /** Get total row count. */
2833
- getTotalRowCount(): number;
2834
- /** Subscribe to data change notifications. Returns unsubscribe function. */
2835
- subscribe(listener: DataChangeListener): () => void;
2836
- /** Clear all data from the data source. */
2837
- clear(): void;
2838
- /** Move a row from one display position to another. */
2839
- moveRow(fromIndex: number, toIndex: number): void;
2840
- }
2841
- interface MutableClientDataSourceOptions<TData> {
2842
- /** Function to extract unique ID from row. Required. */
2843
- getRowId: (row: TData) => RowId;
2844
- /** Custom field accessor for nested properties. */
2845
- getFieldValue?: (row: TData, field: string) => CellValue;
2846
- /**
2847
- * Lookup for a field's valueFormatter. Lets free-text filter conditions
2848
- * compare against the displayed (formatted) value. Values-mode
2849
- * `selectedValues` compare raw values and never use it.
2850
- */
2851
- getValueFormatter?: (field: string) => ((v: CellValue) => string) | undefined;
2852
- /** Debounce time for transactions in ms. Default 50. Set to 0 for sync. */
2853
- debounceMs?: number;
2854
- /** Callback when transactions are processed. */
2855
- onTransactionProcessed?: (result: TransactionResult) => void;
2856
- /** Use Web Worker for sorting large datasets (default: true) */
2857
- useWorker?: boolean;
2858
- /** Options for parallel sorting (only used when useWorker is true) */
2859
- parallelSort?: ParallelSortOptions | false;
2860
- }
2861
- /**
2862
- * Creates a mutable client-side data source with transaction support.
2863
- * Uses IndexedDataStore for efficient incremental operations.
2864
- * For large datasets, sorting is automatically offloaded to a Web Worker.
2865
- */
2866
- declare function createMutableClientDataSource<TData = unknown>(data: TData[], options: MutableClientDataSourceOptions<TData>): MutableDataSource<TData>;
2867
- //#endregion
2868
- //#region src/filtering/distinct-entries.d.ts
2869
- /** One checkbox row in the values-mode filter popup. */
2870
- interface DistinctValueEntry {
2871
- /** Formatted display string shown next to the checkbox. */
2872
- label: string;
2873
- /** All raw values that format to this label. Ticking the label selects them all. */
2874
- values: CellValue[];
2875
- }
2876
- /**
2877
- * Canonical identity key for a raw cell value, used to compare values-mode
2878
- * selections against cell values without ever consulting a formatter.
2879
- *
2880
- * Type-prefixed so raw `5` and raw `"5"` never collide. Arrays are sorted by
2881
- * their elements' own keys first so element order is irrelevant (same rule as
2882
- * the distinct-value scan). Objects rely on JSON.stringify, so key order matters
2883
- * for them — a pre-existing limitation of distinct-value identity.
2884
- */
2885
- declare const rawValueKey: (value: CellValue) => string;
2886
- /**
2887
- * Whether a cell value counts as blank for filtering purposes: null,
2888
- * undefined, empty string, or empty array (e.g. a tags column with no tags).
2889
- * Blank cells are matched via `TextFilterCondition.includeBlank` — the
2890
- * popup's "(Blanks)" checkbox — never via `selectedValues`.
2891
- */
2892
- declare const isBlankCellValue: (value: CellValue) => boolean;
2893
- /**
2894
- * Group raw distinct values by their display label.
2895
- *
2896
- * Multiple raw values can format to the same label; the returned entry keeps
2897
- * every one of them so that applying the filter selects all rows rendering
2898
- * that label. Blank values are skipped (the popup exposes them through the
2899
- * dedicated "include blanks" checkbox), arrays are normalized to sorted
2900
- * copies, and raws are deduplicated within a group by {@link rawValueKey}.
2901
- */
2902
- declare const groupDistinctValues: (values: readonly CellValue[], formatter?: (v: CellValue) => string) => DistinctValueEntry[];
2903
- /**
2904
- * Map a filter model's raw `selectedValues` back to the popup labels that
2905
- * should render as ticked. A label is ticked when at least one of its raw
2906
- * values is selected (data may have changed since the filter was applied).
2907
- */
2908
- declare const labelsForSelectedValues: (entries: readonly DistinctValueEntry[], selectedValues: ReadonlySet<CellValue>) => Set<string>;
2909
- /**
2910
- * Collect the raw values behind the ticked labels — the set to store in
2911
- * `TextFilterCondition.selectedValues` on apply.
2912
- */
2913
- declare const rawValuesForLabels: (entries: readonly DistinctValueEntry[], labels: ReadonlySet<string>) => Set<CellValue>;
2914
- //#endregion
2915
- //#region src/state-reducer.d.ts
2916
- /**
2917
- * Apply a single instruction to mutable slot/header Maps and return
2918
- * other state changes as a partial object.
2919
- *
2920
- * Returns `null` when only the Maps were mutated (no primitive field changes).
2921
- */
2922
- declare const applyInstruction: <TData = unknown>(instruction: GridInstruction, slots: Map<string, SlotData<TData>>, headers: Map<number, HeaderData>) => Partial<GridState<TData>> | null;
2923
- //#endregion
2924
2091
  //#region src/i18n.d.ts
2925
2092
  /** Labels for the filter operator dropdowns, keyed by semantic meaning. */
2926
2093
  interface GridFilterOperatorLabels {
@@ -2971,6 +2138,10 @@ interface GridLabels {
2971
2138
  addCondition: string;
2972
2139
  /** Remove-condition button glyph */
2973
2140
  removeCondition: string;
2141
+ /** "+ Add group" button */
2142
+ addGroup: string;
2143
+ /** Remove-group button glyph */
2144
+ removeGroup: string;
2974
2145
  /** Clear button */
2975
2146
  clear: string;
2976
2147
  /** Apply button */
@@ -2996,6 +2167,13 @@ interface GridLabels {
2996
2167
  /** Filter operator labels */
2997
2168
  operators: GridFilterOperatorLabels;
2998
2169
  }
2170
+ /**
2171
+ * Consumer overrides for grid labels. Every top-level label and every nested
2172
+ * operator label can be changed independently.
2173
+ */
2174
+ type GridLabelOverrides = Omit<Partial<GridLabels>, "operators"> & {
2175
+ operators?: Partial<GridFilterOperatorLabels>;
2176
+ };
2999
2177
  /** English defaults for every grid label. */
3000
2178
  declare const defaultGridLabels: GridLabels;
3001
2179
  /**
@@ -3003,7 +2181,7 @@ declare const defaultGridLabels: GridLabels;
3003
2181
  * `GridLabels`. Top-level keys are shallow-merged and `operators` is merged
3004
2182
  * one level deep; the defaults are never mutated.
3005
2183
  */
3006
- declare const resolveGridLabels: (overrides?: Partial<GridLabels>) => GridLabels;
2184
+ declare const resolveGridLabels: (overrides?: GridLabelOverrides) => GridLabels;
3007
2185
  /**
3008
2186
  * Interpolate `{token}` placeholders in a label template. Unknown tokens are
3009
2187
  * left untouched and missing params are skipped, so this never throws.
@@ -3143,93 +2321,49 @@ interface TouchScrollDeps<TData = unknown> {
3143
2321
  * touchmove and the end listeners are attached per-gesture, and only when
3144
2322
  * scaling is active — small grids keep fully native, compositor-driven
3145
2323
  * scrolling with zero added cost.
2324
+ *
2325
+ * Collaborators: `TouchPolicy` owns the element's touch-action policy,
2326
+ * `SyntheticScroll` bridges the fractional position to the core, and
2327
+ * `FlingAnimator` runs the release momentum.
3146
2328
  */
3147
2329
  declare class TouchScrollController<TData = unknown> {
3148
2330
  private readonly deps;
2331
+ private readonly scroll;
2332
+ private readonly fling;
3149
2333
  private attachedEl;
2334
+ private policy;
3150
2335
  private gesture;
3151
2336
  private gestureCleanup;
3152
- private flingFrame;
3153
- private flingVelocity;
3154
2337
  private dragFrame;
3155
2338
  private pendingDragTarget;
3156
- private savedOverscrollBehavior;
3157
- private savedTouchAction;
3158
- private overrideActive;
3159
- /** Core whose batch instructions currently drive eager policy syncs */
3160
- private subscribedCore;
3161
- private contentSizeUnsubscribe;
3162
- /** Timestamp of the last slot/render pipeline run (drag or fling) */
3163
- private lastPipelineRunMs;
3164
- /** Smoothed interval between pipeline runs — the device's render pace */
3165
- private pipelineIntervalEmaMs;
3166
- /** Smoothed rAF frame interval measured while a fling ticks */
3167
- private frameIntervalEmaMs;
3168
- /** Latched when measured frames prove per-frame rendering unsustainable */
3169
- private flingThrottled;
3170
2339
  constructor(deps: TouchScrollDeps<TData>);
3171
2340
  attach(): void;
3172
2341
  detach(): void;
3173
2342
  /** Rebind policy updates after the host replaces its GridCore instance. */
3174
2343
  syncCore(): void;
3175
- /**
3176
- * Keep the eager policy sync subscribed to the current core. Browsers —
3177
- * iOS Safari especially — sample `touch-action` at gesture start, so a
3178
- * policy applied inside touchstart only takes effect from the NEXT
3179
- * gesture. Subscribing to the core's content-size instructions applies
3180
- * the policy the moment scaling flips, before any finger goes down.
3181
- * Re-invoked through syncCore when the wrapper rebuilds the core, and from
3182
- * the permanent listeners as a fallback.
3183
- */
3184
- private syncPolicySubscription;
3185
- /**
3186
- * While scroll scaling is active, panning must never be native: declare
3187
- * `touch-action: none` so the browser cannot start a (ratio-amplified)
3188
- * native scroll at all, and contain overscroll so synthetic flings do not
3189
- * chain to the page. Non-scaled grids keep their original native policy.
3190
- */
3191
- private syncTouchPolicy;
3192
2344
  /** Cancel an in-flight fling (call before programmatic scrollTop writes). */
3193
2345
  stop(): void;
3194
- /**
3195
- * Drive the grid from the synthetic (fractional) scroll position. The DOM
3196
- * scrollTop write is quantized by the browser and only keeps the scrollbar
3197
- * in sync; the override + direct setViewport carry the sub-pixel position,
3198
- * so rows glide instead of stepping one DOM-pixel's worth of rows at a
3199
- * time under high compression.
3200
- */
3201
- private applySyntheticScrollTop;
3202
- /**
3203
- * Decide whether a fast fling must fall back to throttled rendering.
3204
- * The default is a full pipeline run every frame — a reduced cadence at
3205
- * low speed reads as rows locking and snapping. Only when the measured
3206
- * frame pace shows the device cannot sustain per-frame renders does the
3207
- * fling latch onto the throttled cadence, and it stays latched until the
3208
- * fling slows below the row-flux threshold so the cadence never
3209
- * oscillates.
3210
- */
3211
- private updateFlingThrottle;
3212
- private isFlingPipelineDue;
3213
- /** Hand scroll-position ownership back to native scroll events. */
3214
- private releaseScrollOverride;
2346
+ private resolveContext;
3215
2347
  private readonly onWheel;
3216
2348
  private readonly onTouchStart;
3217
- private readonly startTouchGesture;
2349
+ private startTouchGesture;
3218
2350
  private attachGestureListeners;
3219
2351
  private clearGesture;
3220
- private findTrackedTouch;
2352
+ /** Drop the gesture and hand scrolling back to the browser. */
2353
+ private abandonGesture;
2354
+ private trackedTouch;
3221
2355
  private readonly onTouchMove;
3222
- /**
3223
- * True when the scroll position no longer matches what this controller
3224
- * wrote: a native scroller is moving the element between our frames. Our
3225
- * own writes only diverge by browser rounding, well under the threshold.
3226
- */
3227
- private hasNativeScrollTakenOver;
3228
2356
  private scheduleDragApply;
3229
2357
  private flushPendingDrag;
2358
+ /**
2359
+ * Render a drag position. While the finger is down the workload is
2360
+ * self-limiting (content moves at most one screen per gesture), so every
2361
+ * coalesced frame runs the full pipeline — throttling under the finger
2362
+ * reads as jank, not speed.
2363
+ */
2364
+ private applyDragTarget;
3230
2365
  private readonly onTouchEnd;
3231
2366
  private readonly onTouchCancel;
3232
- private startFling;
3233
2367
  }
3234
2368
  //#endregion
3235
2369
  //#region src/adapter/batch-applier.d.ts
@@ -3370,4 +2504,4 @@ declare class InputEventAdapter<TData = unknown> {
3370
2504
  private dispatchCellDragStart;
3371
2505
  }
3372
2506
  //#endregion
3373
- export { type AssignSlotInstruction, AutoScrollDriver, type BatchChangeSetters, type BatchInstructionListener, type CalculateFillHandlePositionParams, type CancelColumnMoveInstruction, type CancelColumnResizeInstruction, type CancelFillInstruction, type CancelRowDragInstruction, type CellDataType, type CellPointerAction, type CellPosition, type CellRange, type CellRendererParams, type CellValue, type CellValueChangedEvent, type CloseFilterPopupInstruction, type ColumnDefinition, type ColumnFilterModel, type ColumnMoveDragState, type ColumnResizeDragState, type ColumnScrollGeometry, type ColumnsChangedInstruction, type CommitColumnMoveInstruction, type CommitColumnResizeInstruction, type CommitEditInstruction, type CommitFillInstruction, type CommitRowDragInstruction, type ContainerBounds, type CreateSlotInstruction, type DataChangeListener, type DataErrorInstruction, type DataLoadedInstruction, type DataLoadingInstruction, type DataSource, type DataSourceLoadMode, DataSourceOwner, type DataSourceRange, type DataSourceRequest, type DataSourceResponse, type DateFilterCondition, type DateFilterOperator, type DestroySlotInstruction, type Direction, type DistinctValueEntry, type DragEndResult, type DragMoveResult, type DragState, EditManager, type EditManagerOptions, type EditRendererParams, type EditState, type FillHandlePosition, type FillHandleState, FillManager, type FillPointerAction, type FilterCombination, type FilterCondition, type FilterModel, type FilterOperatorOption, type FilterPopupState, GridCore, type GridCoreOptions, type GridFilterOperatorLabels, type GridInstruction, type GridLabels, type GridState, type HeaderData, type HeaderRendererParams, type HighlightContext, HighlightManager, type HighlightingOptions, IndexedDataStore, type IndexedDataStoreOptions, type InitialStateArgs, InputEventAdapter, type InputEventAdapterDeps, InputHandler, type InputHandlerDeps, type InputResult, type InstructionListener, type KeyEventData, type KeyboardResult, type MoveSlotInstruction, type MultiColumnSortedChunk, type MutableClientDataSourceOptions, type MutableDataSource, type NumberFilterCondition, type NumberFilterOperator, type OpenFilterPopupInstruction, ParallelSortManager, type ParallelSortOptions, PendingCellTapController, type PendingCellTapDeps, PendingRowDragController, type PendingRowDragDeps, type PointerEventData, type PopupPosition, ROW_DRAG_HOLD_MS, type RowCacheEviction, type RowCacheOptions, RowDataManager, type RowDataManagerOptions, type RowDragState, type RowId, type RowLoadingMode, type RowLoadingOptions, RowMutationManager, type RowMutationManagerOptions, type RowSortCache, type RowsAddedInstruction, type RowsRemovedInstruction, type RowsUpdatedInstruction, ScrollVirtualizationManager, type ScrollVirtualizationManagerOptions, SelectionManager, type SelectionState, type ServerDataSourceOptions, type SetActiveCellInstruction, type SetContentSizeInstruction, type SetHoverPositionInstruction, type SetSelectionRangeInstruction, type SlotData, type BatchInstructionListener$1 as SlotPoolBatchListener, SlotPoolManager, type SlotPoolManagerOptions, type SlotState, type SortDirection, SortFilterManager, type SortFilterManagerOptions, type SortModel, type SortedChunk, type StartColumnMoveInstruction, type StartColumnResizeInstruction, type StartEditInstruction, type StartFillInstruction, type StartPeekInstruction, type StartRowDragInstruction, type StopEditInstruction, type StopPeekInstruction, TAP_SLOP_PX, type TextFilterCondition, type TextFilterOperator, TouchScrollController, type TouchScrollDeps, type Transaction, TransactionManager, type TransactionManagerOptions, type TransactionProcessedInstruction, type TransactionResult, type UpdateColumnMoveInstruction, type UpdateColumnResizeInstruction, type UpdateFillInstruction, type UpdateHeaderInstruction, type UpdateRowDragInstruction, type VisibleColumnInfo, WorkerPool, type WorkerPoolOptions, applyBatchInstructions, applyInstruction, bindPeekSelectAll, buildCellClasses, calculateColumnPositions, calculateFillHandlePosition, calculateFilterPopupPosition, calculateScaledColumnPositions, compareValues, computeValueHash, createClientDataSource, createDataSourceFromArray, createInitialState, createMutableClientDataSource, createServerDataSource, defaultGridLabels, detectBoundaryCollisions, evaluateColumnFilter, evaluateDateCondition, evaluateNumberCondition, evaluateTextCondition, findColumnAtX, findSlotForRow, formatCellValue, formatLabel, getDateOperatorOptions, getFieldValue, getNumberOperatorOptions, getTextOperatorOptions, getTotalWidth, groupDistinctValues, isBlankCellValue, isCellActive, isCellEditing, isCellInFillPreview, isCellSelected, isColumnInSelectionRange, isRowInSelectionRange, isRowVisible, isSameDay, kWayMerge, kWayMergeMultiColumn, labelsForSelectedValues, rawValueKey, rawValuesForLabels, resolveGridLabels, rowPassesFilter, scrollCellIntoView, setFieldValue, stringToSortableNumber, toPointerEventData };
2507
+ export { type AssignSlotInstruction, AutoScrollDriver, type BatchChangeSetters, type BatchInstructionListener, type CalculateFillHandlePositionParams, type CancelFillInstruction, type CellDataType, type CellPointerAction, type CellPosition, type CellRange, type CellRendererParams, type CellValue, type CellValueChangedEvent, type CloseFilterPopupInstruction, type ColumnDefinition, type ColumnFilterInput, type ColumnFilterModel, type ColumnMoveDragState, type ColumnResizeDragState, type ColumnScrollGeometry, type ColumnsChangedInstruction, type CommitEditInstruction, type CommitFillInstruction, type ContainerBounds, type CreateSlotInstruction, type DataChangeListener, type DataErrorInstruction, type DataLoadedInstruction, type DataLoadingInstruction, type DataSource, type DataSourceLoadMode, DataSourceOwner, type DataSourceRange, type DataSourceRequest, type DataSourceResponse, type DateFilterCondition, type DateFilterOperator, type DestroySlotInstruction, type Direction, type DistinctValueEntry, type DragEndResult, type DragMoveResult, type DragState, type EditRendererParams, type EditState, type FillHandlePosition, type FillHandleState, type FillPointerAction, type FilterCombination, type FilterCondition, type FilterConditionGroup, type FilterModel, type FilterOperatorOption, type FilterPopupState, GridCore, type GridCoreOptions, type GridFilterOperatorLabels, type GridInstruction, type GridLabelOverrides, type GridLabels, type GridState, type HeaderData, type HeaderRendererParams, type HighlightContext, type HighlightingOptions, IndexedDataStore, type IndexedDataStoreOptions, type InitialStateArgs, InputEventAdapter, type InputEventAdapterDeps, InputHandler, type InputHandlerDeps, type InputResult, type InstructionListener, type KeyEventData, type KeyboardResult, type LegacyColumnFilterModel, type LegacyFilterCondition, type MoveSlotInstruction, type MutableClientDataSourceOptions, type MutableDataSource, type NumberFilterCondition, type NumberFilterOperator, type OpenFilterPopupInstruction, type ParallelSortOptions, PendingCellTapController, type PendingCellTapDeps, PendingRowDragController, type PendingRowDragDeps, type PointerEventData, type PopupPosition, ROW_DRAG_HOLD_MS, type RowCacheEviction, type RowCacheOptions, type RowDragState, type RowId, type RowLoadingMode, type RowLoadingOptions, type SelectionState, type ServerDataSourceOptions, type SetActiveCellInstruction, type SetContentSizeInstruction, type SetHoverPositionInstruction, type SetSelectionRangeInstruction, type SlotData, type SlotState, type SortDirection, type SortModel, type StartEditInstruction, type StartFillInstruction, type StartPeekInstruction, type StopEditInstruction, type StopPeekInstruction, TAP_SLOP_PX, type TextFilterCondition, type TextFilterOperator, TouchScrollController, type TouchScrollDeps, type Transaction, TransactionManager, type TransactionManagerOptions, type TransactionResult, type UpdateFillInstruction, type UpdateHeaderInstruction, type VisibleColumnInfo, applyBatchInstructions, applyInstruction, bindPeekSelectAll, buildCellClasses, calculateColumnPositions, calculateFillHandlePosition, calculateFilterPopupPosition, calculateScaledColumnPositions, createClientDataSource, createDataSourceFromArray, createInitialState, createMutableClientDataSource, createServerDataSource, defaultGridLabels, evaluateColumnFilter, evaluateDateCondition, evaluateNumberCondition, evaluateTextCondition, findColumnAtX, formatCellValue, formatLabel, getDateOperatorOptions, getFieldValue, getNumberOperatorOptions, getTextOperatorOptions, getTotalWidth, groupDistinctValues, isBlankCellValue, isCellActive, isCellEditing, isCellInFillPreview, isCellSelected, isLegacyColumnFilterModel, isRowVisible, isSameDay, labelsForSelectedValues, normalizeColumnFilterModel, rawValueKey, rawValuesForLabels, resolveGridLabels, rowPassesFilter, scrollCellIntoView, setFieldValue, toPointerEventData };