handsontable 18.0.0 → 18.1.0-rc7

package/plugins/nestedHeaders/nestedHeaders.mjs

@@ -57,6 +57,7 @@ import { ACTIVE_HEADER_TYPE, HEADER_TYPE } from '../../selection/index.mjs';
 import { BasePlugin } from '../base/index.mjs';
 import StateManager from './stateManager/index.mjs';
 import { createColumnVisibilityAdapter } from './stateManager/columnVisibility.mjs';
+import { createColumnArrangementAdapter } from './stateManager/columnArrangement.mjs';
 import GhostTable from './utils/ghostTable.mjs';
 import { resolveRowspanNavigationContextRow } from './utils/navigation.mjs';
 export const PLUGIN_KEY = 'nestedHeaders';
@@ -64,13 +65,61 @@ export const PLUGIN_PRIORITY = 280;
 var /**
    * Manages the state tree of nested header spans and their visibility.
    */ _stateManager = /*#__PURE__*/ new WeakMap(), /**
+   * Set by afterColumnMove when a move runs inside a batched (suspended) index operation. The
+   * structure cannot be re-derived there (the mapper's caches are stale until resume), so the rebuild
+   * is deferred to the cacheUpdated that fires on resume, where the visual<->physical mapping is fresh.
+   */ _structureRebuildPending = /*#__PURE__*/ new WeakMap(), /**
+   * The physical indexes of the columns a move is relocating, captured in `beforeColumnMove` (where
+   * the pre-move mapping is fresh). After the move, `#reparentMovedColumns` translates them to their
+   * new visual positions and re-parents them into the cohesive group they were dropped inside. Cleared
+   * once consumed. Null when no move is in flight.
+   */ _movedPhysicalColumns = /*#__PURE__*/ new WeakMap(), /**
+   * The column index sequence captured in `beforeColumnMove`, before the move is applied. Compared
+   * against the post-move sequence so a no-op move (e.g. clicking a selected group header, which
+   * "moves" the columns to their own position) skips re-parenting - recomputing membership there
+   * would needlessly drop a column's existing adoption. Null when no move is in flight.
+   */ _preMoveColumnSequence = /*#__PURE__*/ new WeakMap(), /**
    * Handler bound to columnIndexMapper's cacheUpdated local hook. Keeps header colspan state
    * in sync with the current hiding map whenever visibility or column order changes.
    */ _onColumnIndexMapperCacheUpdated = /*#__PURE__*/ new WeakMap(), /**
+   * Handler bound to the afterColumnMove hook. A non-batched move is re-derived directly by
+   * #onColumnIndexMapperCacheUpdated (the cache update carries the 'move' source). A batched move's
+   * cache update fires on resume with the source already cleared, so flag a pending rebuild here -
+   * the resume cache update consumes it once the mapping is fresh.
+   */ _onAfterColumnMove = /*#__PURE__*/ new WeakMap(), /**
+   * Handler bound to the beforeColumnMove hook. Captures the moved columns as physical indexes while
+   * the pre-move mapping is fresh; `#reparentMovedColumns` consumes them after the move to re-parent
+   * each into the cohesive group it lands inside (or standalone).
+   *
+   * @param {number[]} movedColumns Visual indexes of the columns being moved.
+   * @param {number} finalIndex The target visual index (unused).
+   * @param {number|undefined} dropIndex The drop visual index (unused).
+   * @param {boolean} movePossible Whether the move can be performed.
+   */ _onBeforeColumnMove = /*#__PURE__*/ new WeakMap(), /**
+   * Re-parents the columns captured by `#onBeforeColumnMove` after the move completes. Translates the
+   * stored physical indexes to their new visual positions (the mapping is fresh by the time this runs)
+   * and hands them to the state manager, which records the membership overrides the derive needs to
+   * keep `columnDropMode: 'adopt'` groups cohesive.
+   */ _reparentMovedColumns = /*#__PURE__*/ new WeakSet(), /**
+   * Reports whether the captured moved columns account for the whole reordering between the pre-move
+   * and current physical index sequences. Removing those columns from both sequences must leave
+   * identical residuals, which holds by construction for any single `moveIndexes` call and fails when
+   * the cache update came from an unrelated reordering consuming a stale capture.
+   *
+   * @param {number[]} movedPhysicalColumns The physical indexes captured before the move.
+   * @param {number[]} previousSequence The physical index sequence captured before the move.
+   * @param {number[]} currentSequence The physical index sequence after the move.
+   * @returns {boolean} `true` when the captured columns explain the observed reordering.
+   */ _capturedMoveExplainsReorder = /*#__PURE__*/ new WeakSet(), /**
    * Stores the initial focus coordinates before a column header click initiates a range selection.
    */ _focusInitialCoords = /*#__PURE__*/ new WeakMap(), /**
    * Indicates whether a column selection drag triggered by a nested header click is currently in progress.
    */ _isColumnsSelectionInProgress = /*#__PURE__*/ new WeakMap(), /**
+   * Holds the columns to be selected when the pointer moves over a nested header during a drag. The selection
+   * is applied in the `afterOnCellMouseOver` hook so that it stays gated by `stopImmediatePropagation` called
+   * in a `beforeOnCellMouseOver` listener - mirroring how the mouse-down path applies its selection in
+   * `afterOnCellMouseDown`. Reset on every `beforeOnCellMouseOver` to avoid applying a stale range.
+   */ _columnsToSelectOnMouseOver = /*#__PURE__*/ new WeakMap(), /**
    * Keeps the last highlight position made by column selection. The coords are necessary to scroll
    * the viewport to the correct position when the nested header is clicked when the `navigableHeaders`
    * option is disabled.
@@ -142,8 +191,16 @@ var /**
    */ _onBeforeOnCellMouseDown = /*#__PURE__*/ new WeakMap(), /**
    * Initiates a column selection when a nested header cell is clicked, selecting all columns covered by the header span.
    */ _onAfterOnCellMouseDown = /*#__PURE__*/ new WeakMap(), /**
-   * Extends the column selection range when the pointer moves over a nested header cell during a drag selection.
+   * Computes the column selection range when the pointer moves over a nested header cell during a drag
+   * selection and stores it for the `afterOnCellMouseOver` hook to apply. Blocks the core's default
+   * selection handling through the `controller` so the range is driven solely by this plugin. The actual
+   * selection is deferred to `afterOnCellMouseOver` so it stays cancellable through `stopImmediatePropagation`.
    */ _onBeforeOnCellMouseOver = /*#__PURE__*/ new WeakMap(), /**
+   * Applies the column selection computed in `beforeOnCellMouseOver`. Running in the `afterOnCellMouseOver`
+   * hook keeps the selection cancellable - the core skips this hook when `stopImmediatePropagation` is called
+   * in a `beforeOnCellMouseOver` listener, so a drag over nested headers can be blocked the same way it is for
+   * regular column headers.
+   */ _onAfterOnCellMouseOver = /*#__PURE__*/ new WeakMap(), /**
    * Clears the in-progress column selection flag when the pointer button is released.
    */ _onBeforeOnCellMouseUp = /*#__PURE__*/ new WeakMap(), /**
    * Adjusts the selection highlight position when navigable headers are enabled and a multi-column header is selected.
@@ -154,8 +211,19 @@ var /**
    */ _onBeforeSelectColumns = /*#__PURE__*/ new WeakMap(), /**
    * Replaces the default column header renderer array with layer-specific renderers generated by this plugin.
    */ _onAfterGetColumnHeaderRenderers = /*#__PURE__*/ new WeakMap(), /**
-   * Extends the viewport start column to include any header spans that begin outside the calculated viewport boundary.
+   * Extends the viewport's rendered column range so that every nested header group intersecting
+   * the viewport is rendered in full. A wide colspan straddling a viewport edge would otherwise
+   * render only partially, so its `<th>` width changes as columns enter or leave the render range
+   * while scrolling - which makes the center-aligned header label jump. Expanding both the start
+   * and the end boundary to the group's edges keeps each colspan `<th>` at a constant width while
+   * the group is visible (issue #4628).
    */ _onAfterViewportColumnCalculatorOverride = /*#__PURE__*/ new WeakMap(), /**
+   * Extends the viewport start column to include any header spans that begin before the calculated
+   * viewport start boundary.
+   */ _extendViewportStartColumn = /*#__PURE__*/ new WeakSet(), /**
+   * Extends the viewport end column to include any header spans that end after the calculated
+   * viewport end boundary, keeping a colspan header that straddles the right edge fully rendered.
+   */ _extendViewportEndColumn = /*#__PURE__*/ new WeakSet(), /**
    * `modifyColWidth` hook callback - returns width from cache, when is greater than incoming from hook.
    *
    * When `autoColumnSize` is explicitly disabled, the user opts out of auto-sizing
@@ -194,6 +262,7 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
    *
    * @param {number} visualColumnIndex A visual column index from which the columns were removed.
    * @param {number} amount The number of removed columns.
+   * @param {number[]} physicalColumns The physical indexes of the removed columns.
    */ _onAfterRemoveCol = /*#__PURE__*/ new WeakMap(), /**
    * Builds the widths map before the view is rendered.
    */ _onBeforeViewRender = /*#__PURE__*/ new WeakMap();
@@ -301,9 +370,12 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
         this.addHook('afterLoadData', _class_private_field_get(this, _onAfterLoadData));
         this.addHook('afterCreateCol', _class_private_field_get(this, _onAfterCreateCol));
         this.addHook('afterRemoveCol', _class_private_field_get(this, _onAfterRemoveCol));
+        this.addHook('beforeColumnMove', _class_private_field_get(this, _onBeforeColumnMove));
+        this.addHook('afterColumnMove', _class_private_field_get(this, _onAfterColumnMove));
         this.addHook('beforeOnCellMouseDown', _class_private_field_get(this, _onBeforeOnCellMouseDown));
         this.addHook('afterOnCellMouseDown', _class_private_field_get(this, _onAfterOnCellMouseDown));
         this.addHook('beforeOnCellMouseOver', _class_private_field_get(this, _onBeforeOnCellMouseOver));
+        this.addHook('afterOnCellMouseOver', _class_private_field_get(this, _onAfterOnCellMouseOver));
         this.addHook('beforeOnCellMouseUp', _class_private_field_get(this, _onBeforeOnCellMouseUp));
         this.addHook('beforeSelectionHighlightSet', _class_private_field_get(this, _onBeforeSelectionHighlightSet));
         this.addHook('modifyTransformStart', _class_private_field_get(this, _onModifyTransformStart));
@@ -338,6 +410,8 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
         _class_private_field_set(this, _rowspanHeaderNavigationContextRow, null);
         _class_private_field_set(this, _expectedNextKeyboardHighlightCoords, null);
         _class_private_field_get(this, _stateManager).setColumnsLimit(this.hot.countCols());
+        // Derive the header structure against the live column arrangement so it follows column moves.
+        _class_private_field_get(this, _stateManager).setColumnArrangement(createColumnArrangementAdapter(this.hot));
         if (Array.isArray(nestedHeaders)) {
             this.detectedOverlappedHeaders = _class_private_field_get(this, _stateManager).setState(nestedHeaders);
         }
@@ -507,18 +581,36 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
         return _class_private_field_get(this, _stateManager).getHeaderTreeNodeData(coords.row, coords.col);
     }
     constructor(...args){
-        super(...args), _class_private_method_init(this, _applyColspan), _class_private_method_init(this, _applyRowspan), _class_private_method_init(this, _findRenderableHeaderRow), _class_private_method_init(this, _getRootHeaderRowspan), _class_private_method_init(this, _isNavigableHeaderCell), _class_private_method_init(this, _findNearestNavigableHeaderColumn), _class_private_field_init(this, _stateManager, {
+        super(...args), _class_private_method_init(this, _reparentMovedColumns), _class_private_method_init(this, _capturedMoveExplainsReorder), _class_private_method_init(this, _applyColspan), _class_private_method_init(this, _applyRowspan), _class_private_method_init(this, _findRenderableHeaderRow), _class_private_method_init(this, _getRootHeaderRowspan), _class_private_method_init(this, _isNavigableHeaderCell), _class_private_method_init(this, _findNearestNavigableHeaderColumn), _class_private_method_init(this, _extendViewportStartColumn), _class_private_method_init(this, _extendViewportEndColumn), _class_private_field_init(this, _stateManager, {
+            writable: true,
+            value: void 0
+        }), _class_private_field_init(this, _structureRebuildPending, {
+            writable: true,
+            value: void 0
+        }), _class_private_field_init(this, _movedPhysicalColumns, {
+            writable: true,
+            value: void 0
+        }), _class_private_field_init(this, _preMoveColumnSequence, {
             writable: true,
             value: void 0
         }), _class_private_field_init(this, _onColumnIndexMapperCacheUpdated, {
             writable: true,
             value: void 0
+        }), _class_private_field_init(this, _onAfterColumnMove, {
+            writable: true,
+            value: void 0
+        }), _class_private_field_init(this, _onBeforeColumnMove, {
+            writable: true,
+            value: void 0
         }), _class_private_field_init(this, _focusInitialCoords, {
             writable: true,
             value: void 0
         }), _class_private_field_init(this, _isColumnsSelectionInProgress, {
             writable: true,
             value: void 0
+        }), _class_private_field_init(this, _columnsToSelectOnMouseOver, {
+            writable: true,
+            value: void 0
         }), _class_private_field_init(this, _recentlyHighlightCoords, {
             writable: true,
             value: void 0
@@ -557,6 +649,9 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
         }), _class_private_field_init(this, _onBeforeOnCellMouseOver, {
             writable: true,
             value: void 0
+        }), _class_private_field_init(this, _onAfterOnCellMouseOver, {
+            writable: true,
+            value: void 0
         }), _class_private_field_init(this, _onBeforeOnCellMouseUp, {
             writable: true,
             value: void 0
@@ -602,10 +697,33 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
         }), _class_private_field_init(this, _onBeforeViewRender, {
             writable: true,
             value: void 0
-        }), _class_private_field_set(this, _stateManager, new StateManager()), _class_private_field_set(this, _onColumnIndexMapperCacheUpdated, ({ hiddenIndexesChanged })=>{
+        }), _class_private_field_set(this, _stateManager, new StateManager()), _class_private_field_set(this, _structureRebuildPending, false), _class_private_field_set(this, _movedPhysicalColumns, null), _class_private_field_set(this, _preMoveColumnSequence, null), _class_private_field_set(this, _onColumnIndexMapperCacheUpdated, ({ indexesSequenceChanged, hiddenIndexesChanged })=>{
             if (!this.enabled) {
                 return;
             }
+            // A column move changes the visual<->physical mapping without mutating the authored settings, so
+            // re-derive the header tree to make the structure (labels and group spans) follow the data; a
+            // group whose columns are no longer adjacent renders as multiple same-label banners. A non-batched
+            // move carries the 'move' change source on this cache update. A batched / suspended move's cache
+            // update fires on resume with the source already cleared, so afterColumnMove flags a pending
+            // rebuild for that case. Both re-derive here, where the mapping is fresh. The 'move' gate excludes
+            // init / insert / remove, which rebuild through their own paths (setState, afterCreateCol,
+            // afterRemoveCol) and would otherwise be double-processed (e.g. re-applying a collapse twice).
+            const isColumnMove = indexesSequenceChanged && this.hot.columnIndexMapper.indexesChangeSource === 'move';
+            if (isColumnMove || _class_private_field_get(this, _structureRebuildPending)) {
+                // Re-parent the moved columns first (cohesive groups adopt/release members), then re-derive so
+                // the tree reflects both the new arrangement and the membership changes.
+                _class_private_method_get(this, _reparentMovedColumns, reparentMovedColumns).call(this);
+                _class_private_field_get(this, _stateManager).rebuildState();
+                // Only release the captured move state once it has been consumed here. A move that splits a
+                // collapsed group makes CollapsibleColumns expand it from its own beforeColumnMove handler; that
+                // expansion mutates the hiding map and fires a synchronous cacheUpdated (hiddenIndexesChanged
+                // only) before moveIndexes runs. Clearing the capture unconditionally on that intermediate update
+                // dropped #movedPhysicalColumns, so the real move's cacheUpdated found nothing to re-parent.
+                _class_private_field_set(this, _structureRebuildPending, false);
+                _class_private_field_set(this, _movedPhysicalColumns, null);
+                _class_private_field_set(this, _preMoveColumnSequence, null);
+            }
             // syncVisibility must run on every cache update (including a pure column move) so the tree's
             // colspan / isHidden stay aligned with the current visual<->physical mapping (DEV-1717).
             _class_private_field_get(this, _stateManager).syncVisibility(createColumnVisibilityAdapter(this.hot));
@@ -616,7 +734,16 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
             if (hiddenIndexesChanged) {
                 this.ghostTable.buildWidthsMap();
             }
-        }), _class_private_field_set(this, _focusInitialCoords, null), _class_private_field_set(this, _isColumnsSelectionInProgress, false), _class_private_field_set(this, _recentlyHighlightCoords, null), _class_private_field_set(this, _rowspanHeaderNavigationContextRow, null), _class_private_field_set(this, _expectedNextKeyboardHighlightCoords, null), _class_private_field_set(this, _updateWidthsMap, false), /**
+        }), _class_private_field_set(this, _onAfterColumnMove, ()=>{
+            if (this.enabled && this.hot.columnIndexMapper.isBatched) {
+                _class_private_field_set(this, _structureRebuildPending, true);
+            }
+        }), _class_private_field_set(this, _onBeforeColumnMove, (movedColumns, finalIndex, dropIndex, movePossible)=>{
+            if (this.enabled && movePossible !== false) {
+                _class_private_field_set(this, _movedPhysicalColumns, movedColumns.map((visualColumn)=>this.hot.toPhysicalColumn(visualColumn)));
+                _class_private_field_set(this, _preMoveColumnSequence, this.hot.columnIndexMapper.getIndexesSequence());
+            }
+        }), _class_private_field_set(this, _focusInitialCoords, null), _class_private_field_set(this, _isColumnsSelectionInProgress, false), _class_private_field_set(this, _columnsToSelectOnMouseOver, null), _class_private_field_set(this, _recentlyHighlightCoords, null), _class_private_field_set(this, _rowspanHeaderNavigationContextRow, null), _class_private_field_set(this, _expectedNextKeyboardHighlightCoords, null), _class_private_field_set(this, _updateWidthsMap, false), /**
    * Custom helper for getting widths of the nested headers.
    */ // @TODO This should be changed after refactor handsontable/utils/ghostTable.
         this.ghostTable = new GhostTable({
@@ -799,6 +926,7 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
                 selection.selectColumns(...columnsToSelect);
             }
         }), _class_private_field_set(this, _onBeforeOnCellMouseOver, (event, coords, TD, controller)=>{
+            _class_private_field_set(this, _columnsToSelectOnMouseOver, null);
             if (!this.hot.view.isMouseDown() || controller.column) {
                 return;
             }
@@ -837,6 +965,13 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
                     headerLevel
                 ];
             }
+            _class_private_field_set(this, _columnsToSelectOnMouseOver, columnsToSelect);
+        }), _class_private_field_set(this, _onAfterOnCellMouseOver, ()=>{
+            if (_class_private_field_get(this, _columnsToSelectOnMouseOver) === null) {
+                return;
+            }
+            const columnsToSelect = _class_private_field_get(this, _columnsToSelectOnMouseOver);
+            _class_private_field_set(this, _columnsToSelectOnMouseOver, null);
             this.hot.selection.selectColumns(...columnsToSelect);
         }), _class_private_field_set(this, _onBeforeOnCellMouseUp, ()=>{
             _class_private_field_set(this, _isColumnsSelectionInProgress, false);
@@ -1018,21 +1153,8 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
                 }
             }
         }), _class_private_field_set(this, _onAfterViewportColumnCalculatorOverride, (calc)=>{
-            const headerLayersCount = _class_private_field_get(this, _stateManager).getLayersCount();
-            let newStartColumn = calc.startColumn;
-            let nonRenderable = !!headerLayersCount;
-            for(let headerLayer = 0; headerLayer < headerLayersCount; headerLayer++){
-                const startColumn = _class_private_field_get(this, _stateManager).findLeftMostColumnIndex(headerLayer, calc.startColumn);
-                const renderedStartColumn = this.hot.columnIndexMapper.getRenderableFromVisualIndex(startColumn);
-                if (startColumn >= 0) {
-                    nonRenderable = false;
-                }
-                if (isNumeric(renderedStartColumn) && renderedStartColumn !== null && renderedStartColumn < calc.startColumn) {
-                    newStartColumn = renderedStartColumn;
-                    break;
-                }
-            }
-            calc.startColumn = nonRenderable ? _class_private_field_get(this, _stateManager).getHeaderTreeNodeData(0, newStartColumn)?.columnIndex ?? newStartColumn : newStartColumn;
+            _class_private_method_get(this, _extendViewportStartColumn, extendViewportStartColumn).call(this, calc);
+            _class_private_method_get(this, _extendViewportEndColumn, extendViewportEndColumn).call(this, calc);
         }), _class_private_field_set(this, _onModifyColWidth, (width, column)=>{
             if (this.hot.getSettings().autoColumnSize === false) {
                 return width;
@@ -1067,10 +1189,13 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
                 this.updatePlugin();
             }
         }), _class_private_field_set(this, _onAfterCreateCol, (visualColumnIndex, amount)=>{
-            _class_private_field_get(this, _stateManager).insertColumns(visualColumnIndex, amount);
+            // The authored header settings are keyed by physical column, but the hook reports a visual index.
+            // Translate it so the structure stays aligned after a column move, where visual != physical.
+            const physicalColumnIndex = this.hot.columnIndexMapper.getPhysicalFromVisualIndex(visualColumnIndex) ?? visualColumnIndex;
+            _class_private_field_get(this, _stateManager).insertColumns(visualColumnIndex, physicalColumnIndex, amount);
             _class_private_field_set(this, _updateWidthsMap, true);
-        }), _class_private_field_set(this, _onAfterRemoveCol, (visualColumnIndex, amount)=>{
-            _class_private_field_get(this, _stateManager).removeColumns(visualColumnIndex, amount);
+        }), _class_private_field_set(this, _onAfterRemoveCol, (visualColumnIndex, amount, physicalColumns)=>{
+            _class_private_field_get(this, _stateManager).removeColumns(visualColumnIndex, amount, physicalColumns);
             _class_private_field_set(this, _updateWidthsMap, true);
         }), _class_private_field_set(this, _onBeforeViewRender, ()=>{
             if (_class_private_field_get(this, _updateWidthsMap)) {
@@ -1080,6 +1205,44 @@ _onInit = /*#__PURE__*/ new WeakMap(), /**
         });
     }
 }
+function reparentMovedColumns() {
+    const movedPhysicalColumns = _class_private_field_get(this, _movedPhysicalColumns);
+    const previous = _class_private_field_get(this, _preMoveColumnSequence);
+    if (movedPhysicalColumns === null || previous === null) {
+        return;
+    }
+    // A no-op move (the column order is unchanged - e.g. clicking a selected group header) must not
+    // re-parent: recomputing membership for the "moved" columns would drop a prior adoption and split
+    // the group. Only re-parent when the move actually reordered the columns.
+    const sequence = this.hot.columnIndexMapper.getIndexesSequence();
+    if (previous.length === sequence.length && previous.every((physicalColumn, index)=>physicalColumn === sequence[index])) {
+        return;
+    }
+    // The capture is only valid for the move that produced this cache update. A hard-vetoed move
+    // (a beforeColumnMove handler returning false) leaves the capture set with no move performed, and
+    // a later 'move' cache update from another path (e.g. manualColumnFreeze calling moveIndexes
+    // directly, which skips beforeColumnMove) would then re-parent the stale columns. moveIndexes
+    // rebuilds the sequence as the non-moved columns in their original order with the moved columns
+    // reinserted, so removing the captured columns from both sequences must leave identical residuals.
+    // When they differ, this update came from a different reordering - skip rather than misapply it.
+    if (!_class_private_method_get(this, _capturedMoveExplainsReorder, capturedMoveExplainsReorder).call(this, movedPhysicalColumns, previous, sequence)) {
+        return;
+    }
+    const movedVisualColumns = [];
+    movedPhysicalColumns.forEach((physicalColumn)=>{
+        const visualColumn = this.hot.columnIndexMapper.getVisualFromPhysicalIndex(physicalColumn);
+        if (visualColumn !== null) {
+            movedVisualColumns.push(visualColumn);
+        }
+    });
+    _class_private_field_get(this, _stateManager).reparentColumns(movedVisualColumns);
+}
+function capturedMoveExplainsReorder(movedPhysicalColumns, previousSequence, currentSequence) {
+    const movedSet = new Set(movedPhysicalColumns);
+    const residualBefore = previousSequence.filter((physicalColumn)=>!movedSet.has(physicalColumn));
+    const residualAfter = currentSequence.filter((physicalColumn)=>!movedSet.has(physicalColumn));
+    return residualBefore.length === residualAfter.length && residualBefore.every((physicalColumn, index)=>physicalColumn === residualAfter[index]);
+}
 function applyColspan(TH, colspan, visualColumnIndex, renderedColumnIndex, fixedColumnsStart) {
     if (colspan === undefined || colspan <= 1) {
         return;
@@ -1147,3 +1310,39 @@ function findNearestNavigableHeaderColumn(headerRow, visualColumnIndex, directio
     }
     return null;
 }
+function extendViewportStartColumn(calc) {
+    const headerLayersCount = _class_private_field_get(this, _stateManager).getLayersCount();
+    let newStartColumn = calc.startColumn;
+    let nonRenderable = !!headerLayersCount;
+    for(let headerLayer = 0; headerLayer < headerLayersCount; headerLayer++){
+        const startColumn = _class_private_field_get(this, _stateManager).findLeftMostColumnIndex(headerLayer, calc.startColumn);
+        const renderedStartColumn = this.hot.columnIndexMapper.getRenderableFromVisualIndex(startColumn);
+        if (startColumn >= 0) {
+            nonRenderable = false;
+        }
+        if (isNumeric(renderedStartColumn) && renderedStartColumn !== null && renderedStartColumn < calc.startColumn) {
+            newStartColumn = renderedStartColumn;
+            break;
+        }
+    }
+    calc.startColumn = nonRenderable ? _class_private_field_get(this, _stateManager).getHeaderTreeNodeData(0, newStartColumn)?.columnIndex ?? newStartColumn : newStartColumn;
+}
+function extendViewportEndColumn(calc) {
+    const columnIndexMapper = this.hot.columnIndexMapper;
+    const headerLayersCount = _class_private_field_get(this, _stateManager).getLayersCount();
+    const visualEndColumn = columnIndexMapper.getVisualFromRenderableIndex(calc.endColumn);
+    if (visualEndColumn === null) {
+        return;
+    }
+    for(let headerLayer = 0; headerLayer < headerLayersCount; headerLayer++){
+        const endColumn = _class_private_field_get(this, _stateManager).findRightMostColumnIndex(headerLayer, visualEndColumn);
+        const nearestColumn = columnIndexMapper.getNearestNotHiddenIndex(endColumn, -1);
+        const renderedEndColumn = nearestColumn === null ? null : columnIndexMapper.getRenderableFromVisualIndex(nearestColumn);
+        // The top header layer holds the widest spans, so the first layer that expands the
+        // boundary already yields the largest extent - no deeper layer can exceed it.
+        if (renderedEndColumn !== null && renderedEndColumn > calc.endColumn) {
+            calc.endColumn = renderedEndColumn;
+            break;
+        }
+    }
+}

package/plugins/nestedHeaders/stateManager/columnArrangement.d.mts

@@ -0,0 +1 @@
+export * from './columnArrangement.js';

package/plugins/nestedHeaders/stateManager/columnArrangement.d.ts

@@ -0,0 +1,37 @@
+import type { HotInstance } from '../../../core/types';
+/**
+ * A port that exposes the current visual-to-physical column arrangement, abstracting the
+ * Handsontable column index mapper away from the header-tree derivation logic.
+ *
+ * The nested-header structure is authored in physical-column space (the position of each header in
+ * the `nestedHeaders` settings, where visual equals physical at initialization). Deriving the render
+ * structure means walking the columns in their current visual order and reading the header authored
+ * for whatever physical column now sits at each visual position - which is exactly what this port
+ * provides. It is the structural counterpart to `ColumnVisibility`.
+ */
+export interface ColumnArrangement {
+    /**
+     * Returns the physical column index currently mapped to the given visual column index.
+     *
+     * @param {number} visualColumnIndex - The visual column index to translate.
+     * @returns {number} The physical column index.
+     */
+    getPhysicalFromVisual(visualColumnIndex: number): number;
+}
+/**
+ * Creates a ColumnArrangement port adapter backed by the Handsontable column index mapper.
+ * The adapter reports the live visual-to-physical mapping, so a column move (which reorders the
+ * mapper's index sequence) is reflected the next time the structure is derived.
+ *
+ * @param {HotInstance} hot - The Handsontable instance.
+ * @returns {ColumnArrangement} The arrangement port backed by the column index mapper.
+ */
+export declare function createColumnArrangementAdapter(hot: HotInstance): ColumnArrangement;
+/**
+ * Creates an identity ColumnArrangement where every visual column maps to the same physical column.
+ * This reproduces the pre-move state (visual equals physical) and is used as the regression baseline
+ * and in tests, where deriving against it must yield the same structure as the legacy build.
+ *
+ * @returns {ColumnArrangement} An identity arrangement.
+ */
+export declare function createIdentityColumnArrangement(): ColumnArrangement;

package/plugins/nestedHeaders/stateManager/columnArrangement.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get createColumnArrangementAdapter () {
+        return createColumnArrangementAdapter;
+    },
+    get createIdentityColumnArrangement () {
+        return createIdentityColumnArrangement;
+    }
+});
+function createColumnArrangementAdapter(hot) {
+    return {
+        getPhysicalFromVisual (visualColumnIndex) {
+            const physicalIndex = hot.columnIndexMapper.getPhysicalFromVisualIndex(visualColumnIndex);
+            // A null result means the visual index is out of range; fall back to the identity mapping so
+            // the caller (which only iterates indexes within the authored width) stays well defined.
+            return physicalIndex === null ? visualColumnIndex : physicalIndex;
+        }
+    };
+}
+function createIdentityColumnArrangement() {
+    return {
+        getPhysicalFromVisual (visualColumnIndex) {
+            return visualColumnIndex;
+        }
+    };
+}

package/plugins/nestedHeaders/stateManager/columnArrangement.mjs

@@ -0,0 +1,30 @@
+/**
+ * Creates a ColumnArrangement port adapter backed by the Handsontable column index mapper.
+ * The adapter reports the live visual-to-physical mapping, so a column move (which reorders the
+ * mapper's index sequence) is reflected the next time the structure is derived.
+ *
+ * @param {HotInstance} hot - The Handsontable instance.
+ * @returns {ColumnArrangement} The arrangement port backed by the column index mapper.
+ */ export function createColumnArrangementAdapter(hot) {
+    return {
+        getPhysicalFromVisual (visualColumnIndex) {
+            const physicalIndex = hot.columnIndexMapper.getPhysicalFromVisualIndex(visualColumnIndex);
+            // A null result means the visual index is out of range; fall back to the identity mapping so
+            // the caller (which only iterates indexes within the authored width) stays well defined.
+            return physicalIndex === null ? visualColumnIndex : physicalIndex;
+        }
+    };
+}
+/**
+ * Creates an identity ColumnArrangement where every visual column maps to the same physical column.
+ * This reproduces the pre-move state (visual equals physical) and is used as the regression baseline
+ * and in tests, where deriving against it must yield the same structure as the legacy build.
+ *
+ * @returns {ColumnArrangement} An identity arrangement.
+ */ export function createIdentityColumnArrangement() {
+    return {
+        getPhysicalFromVisual (visualColumnIndex) {
+            return visualColumnIndex;
+        }
+    };
+}

package/plugins/nestedHeaders/stateManager/deriveSettings.d.mts

@@ -0,0 +1 @@
+export * from './deriveSettings.js';

package/plugins/nestedHeaders/stateManager/deriveSettings.d.ts

@@ -0,0 +1,57 @@
+import type { ColumnArrangement } from './columnArrangement';
+import type { SourceHeaderCell } from './sourceSettings';
+/**
+ * Membership overrides re-parent specific columns after a move: `physical column -> header level ->
+ * owner identity`. The owner identity is the destination group's authored owner index (`>= 0`), or a
+ * negative value meaning "standalone" (rendered as its own header). An entry overrides the authored
+ * owner for that column at that level; absence falls back to the authored structure. Only group levels
+ * carry overrides - a leaf always keeps its own label.
+ */
+export type MembershipOverrides = Map<number, Map<number, number>>;
+/**
+ * Computes, for one normalized header layer, the index of the header cell that owns each column.
+ *
+ * In the normalized representation a header that spans N columns is one cell at its left edge with
+ * `origColspan = N`, followed by N-1 placeholder cells. The owner index of every column in that span
+ * is the left-edge index. Because the authored configuration is properly nested, this left-edge
+ * index is a stable identity for the group at that level - two distinct groups (even with the same
+ * label) own different columns, so they never merge when a move makes them adjacent.
+ *
+ * @param {SourceHeaderCell[]} layer - A single normalized header layer (one row of the matrix).
+ * @returns {number[]} For each column index, the owning header cell's index within the layer.
+ */
+export declare function computeOwnerIndex(layer: SourceHeaderCell[]): number[];
+/**
+ * Resolves the group owner key for one physical column at one header level, applying the
+ * standalone-sentinel and override-precedence contract shared by the derive and re-parent logic.
+ *
+ * A membership override (from a column move) wins: a non-negative value is the destination group's
+ * authored owner index, a negative value means standalone. With no override the authored owner index
+ * applies; a physical column with no authored header at this level gets a unique negative key
+ * (`-1 - physical`) so it never coalesces with a real group.
+ *
+ * @param {number} physical - The physical column index.
+ * @param {number[]} ownerIndex - The authored owner index per physical column for this level.
+ * @param {number} [override] - The membership override for this column at this level, if any.
+ * @returns {number} The group owner key (`>= 0` group, `< 0` standalone).
+ */
+export declare function resolveOwnerKey(physical: number, ownerIndex: number[], override?: number): number;
+/**
+ * Derives the visual-order nested-header settings from the authored (physical-order) settings and a
+ * column arrangement. This is the structural counterpart to `syncVisibilityOnTree`: visibility
+ * answers "which columns are hidden", this answers "which header sits over each visual column".
+ *
+ * With an identity arrangement the output equals the authored input, so the legacy build is
+ * reproduced exactly. With a moved arrangement the headers follow their physical columns, and groups
+ * whose columns are no longer adjacent split into several same-label cells (the AG Grid model).
+ *
+ * The output width is the authored column count (every layer is normalized to that width), so the
+ * structure spans exactly the columns the nested-headers definition covers - the same span as the
+ * legacy build. The arrangement supplies only the visual-to-physical mapping.
+ *
+ * @param {SourceHeaderCell[][]} authoredSettings - The normalized header settings in authored order.
+ * @param {ColumnArrangement} arrangement - The current visual-to-physical column arrangement.
+ * @param {MembershipOverrides} [membershipOverrides] - Per-column re-parenting from column moves.
+ * @returns {SourceHeaderCell[][]} The normalized header settings in visual order.
+ */
+export declare function deriveVisualSettings(authoredSettings: SourceHeaderCell[][], arrangement: ColumnArrangement, membershipOverrides?: MembershipOverrides): SourceHeaderCell[][];