handsontable 18.0.0 → 18.1.0-rc7

package/plugins/nestedHeaders/stateManager/index.mjs

@@ -48,15 +48,17 @@ function _class_private_method_init(obj, privateSet) {
     _check_private_redeclaration(obj, privateSet);
     privateSet.add(obj);
 }
-import { arrayMap, arrayReduce } from '../../../helpers/array.mjs';
+import { arrayMap } from '../../../helpers/array.mjs';
 import SourceSettings from './sourceSettings.mjs';
 import HeadersTree from './headersTree.mjs';
 import { triggerNodeModification } from './nodeModifiers/index.mjs';
 import { isDeclarativeGroup } from './nodeModifiers/utils/tree.mjs';
 import { generateMatrix } from './matrixGenerator.mjs';
 import { syncVisibilityOnTree } from './syncVisibility.mjs';
+import { deriveVisualSettings, computeOwnerIndex, resolveOwnerKey } from './deriveSettings.mjs';
+import { createIdentityColumnArrangement } from './columnArrangement.mjs';
 import { TRAVERSAL_DF_PRE } from '../../../utils/dataStructures/tree.mjs';
-var _sourceSettings = /*#__PURE__*/ new WeakMap(), _headersTree = /*#__PURE__*/ new WeakMap(), /**
+var _sourceSettings = /*#__PURE__*/ new WeakMap(), _derivedSettings = /*#__PURE__*/ new WeakMap(), _headersTree = /*#__PURE__*/ new WeakMap(), /**
    * Cached matrix which is generated from the tree structure.
    *
    * @private
@@ -65,6 +67,33 @@ var _sourceSettings = /*#__PURE__*/ new WeakMap(), _headersTree = /*#__PURE__*/
    * The last column-visibility adapter passed to syncVisibility(). Stored so that
    * mapState()/mergeStateWith() can re-apply it after rebuilding the tree.
    */ _lastColumnVisibility = /*#__PURE__*/ new WeakMap(), /**
+   * The column arrangement the headers tree is derived against. When null, an identity arrangement
+   * (visual equals physical) is used, which reproduces the authored structure. The plugin sets a
+   * live adapter so the structure follows column moves.
+   */ _columnArrangement = /*#__PURE__*/ new WeakMap(), /**
+   * Per-column membership overrides set by column moves (`physical -> level -> owner identity`). They
+   * re-parent a moved column into the cohesive (`columnDropMode: 'adopt'`) group it was dropped inside, or
+   * mark it standalone when it left its group - the piece a pure derive cannot infer from the final
+   * arrangement alone. Consumed by `#deriveTree`. Empty means "use the authored structure".
+   */ _membershipOverrides = /*#__PURE__*/ new WeakMap(), /**
+   * Captures the header level and authored group identity of every currently collapsed group, so the
+   * collapsed state can be re-attached after a move re-derives the tree.
+   *
+   * @returns {Array<{headerLevel: number, authoredColumnIndex: number}>}
+   */ _snapshotCollapsedGroups = /*#__PURE__*/ new WeakSet(), /**
+   * Re-collapses the groups captured by #snapshotCollapsedGroups() on the freshly re-derived tree,
+   * matching by authored identity. A group that maps to exactly one node stayed contiguous and is
+   * re-collapsed; a group that maps to more than one node was split by the move and is left expanded.
+   *
+   * @param {Array<{headerLevel: number, authoredColumnIndex: number}>} collapsedGroups The captured groups.
+   */ _reapplyCollapsedGroupsByIdentity = /*#__PURE__*/ new WeakSet(), /**
+   * Finds every tree node at the given header level that was derived from the given authored owner
+   * column. More than one match means the authored group is split across non-adjacent visual columns.
+   *
+   * @param {number} headerLevel Header level index.
+   * @param {number} authoredColumnIndex The authored owner column index identifying the group.
+   * @returns {TreeNode[]} The matching nodes.
+   */ _findNodesByAuthoredIdentity = /*#__PURE__*/ new WeakSet(), /**
    * Rebuilds the header tree after a structural mutation while preserving the collapsed state.
    *
    * Visibility is derived BEFORE re-collapsing, so collapseNode picks the correct first *visible*
@@ -89,6 +118,16 @@ var _sourceSettings = /*#__PURE__*/ new WeakMap(), _headersTree = /*#__PURE__*/
    * @param {Array<{headerLevel: number, columnIndex: number}>} collapsedNodes The captured nodes.
    * @param {Function} shiftColumnIndex Maps an old visual column index to the new one.
    */ _reapplyCollapsedNodes = /*#__PURE__*/ new WeakSet(), /**
+   * Applies a NodeModifiers action to the tree WITHOUT regenerating the state matrix, and reports
+   * whether a node was actually modified. Callers that batch several modifications (re-applying
+   * collapse after a re-derive) use this and regenerate the matrix once at the end, instead of paying
+   * a full whole-matrix regeneration per modified node.
+   *
+   * @param {string} action An action name to trigger.
+   * @param {number} headerLevel Header level index.
+   * @param {number} columnIndex A visual column index.
+   * @returns {{ actionResult: NodeModificationResult|undefined, modified: boolean }}
+   */ _applyNodeModification = /*#__PURE__*/ new WeakSet(), /**
    * Re-applies the last column visibility adapter after a tree rebuild, so that mapState() and
    * mergeStateWith() calls from CollapsibleColumns do not discard visibility state set earlier.
    * The collapsed state is restored separately by #rebuildPreservingCollapse re-running the collapse.
@@ -96,7 +135,36 @@ var _sourceSettings = /*#__PURE__*/ new WeakMap(), _headersTree = /*#__PURE__*/
    * Re-derives tree-node visibility (colspan, isHidden, crossHiddenColumns) from the last column
    * visibility adapter WITHOUT regenerating the state matrix. Used as the first pass of
    * #rebuildPreservingCollapse, where the matrix would be immediately discarded by re-collapsing.
-   */ _deriveVisibility = /*#__PURE__*/ new WeakSet();
+   */ _deriveVisibility = /*#__PURE__*/ new WeakSet(), /**
+   * Derives the visual-order settings from the authored source settings, then builds the headers
+   * tree from them. The headers tree is therefore always a function of the authored configuration
+   * and the current column arrangement. With the identity arrangement the derived settings equal the
+   * authored ones, so the built tree is identical to building directly from the authored settings; a
+   * non-identity arrangement (a column move) makes the structure follow the data.
+   */ _deriveTree = /*#__PURE__*/ new WeakSet(), /**
+   * Resolves the owner a moved column takes at an enclosing level (at or outside its cohesive adoption
+   * level), so the adopted column is contained by the same group its visual neighbors belong to. Uses
+   * the neighbors' shared effective owner when they agree (which keeps the run contiguous, never
+   * straddling), and otherwise falls back to the authored ancestor of the adopted group's anchor.
+   *
+   * @param {number} visualColumn - The column's post-move visual index.
+   * @param {number} level - The enclosing header level.
+   * @param {Function} enclosingOwnerAt - Resolves the owner shared by both neighbors, or -1.
+   * @param {Function} authoredOwnerAt - Resolves the authored owner of a (visual, level).
+   * @param {number[][]} ownerIndexByLevel - The authored owner column index per (level, column).
+   * @returns {number} The owner identity the column takes at this level.
+   */ _adoptedAncestorOwner = /*#__PURE__*/ new WeakSet(), /**
+   * Clears all move-driven membership overrides. Call when the authored structure changes - a fresh
+   * config (setState) or an index-shifting insert/remove - because the overrides are keyed by physical
+   * column and their owner identities index the authored structure, both invalidated by such a change.
+   */ _resetMembershipOverrides = /*#__PURE__*/ new WeakSet(), /**
+   * Records or clears one membership override.
+   *
+   * @param {number} physical - The physical column index.
+   * @param {number} level - The header level.
+   * @param {number|null} identity - The owner identity to record (`>= 0` group, `< 0` standalone), or
+   *   `null` to clear it (fall back to the authored structure).
+   */ _setMembershipOverride = /*#__PURE__*/ new WeakSet();
 class StateManager {
     /**
    * Sets a new state for the nested headers plugin based on settings passed
@@ -106,11 +174,15 @@ class StateManager {
    * @returns {boolean} Returns `true` if the settings are processed correctly, `false` otherwise.
    */ setState(nestedHeadersSettings) {
         _class_private_field_get(this, _sourceSettings).setData(nestedHeadersSettings);
+        // A fresh authored configuration invalidates move-driven membership overrides (their owner
+        // identities index the previous structure), so reset them.
+        _class_private_method_get(this, _resetMembershipOverrides, resetMembershipOverrides).call(this);
         let hasError = false;
         try {
-            _class_private_field_get(this, _headersTree).buildTree();
+            _class_private_method_get(this, _deriveTree, deriveTree).call(this);
         } catch (ex) {
             _class_private_field_get(this, _headersTree).clear();
+            _class_private_field_get(this, _derivedSettings).clear();
             _class_private_field_get(this, _sourceSettings).clear();
             hasError = true;
         }
@@ -125,6 +197,32 @@ class StateManager {
         _class_private_field_get(this, _sourceSettings).setColumnsLimit(columnsCount);
     }
     /**
+   * Sets the column arrangement the headers tree is derived against. Pass a live adapter (backed by
+   * the column index mapper) so the rendered structure follows column moves, or `null` to fall back
+   * to the identity arrangement (authored structure). Does not rebuild on its own - call
+   * `rebuildState()` (or any structural mutation) to re-derive the tree.
+   *
+   * @param {ColumnArrangement|null} columnArrangement The arrangement to derive against, or null.
+   */ setColumnArrangement(columnArrangement) {
+        _class_private_field_set(this, _columnArrangement, columnArrangement);
+    }
+    /**
+   * Re-derives the headers tree from the current authored settings and column arrangement, preserving
+   * the collapsed state and re-applying visibility. Call this when only the arrangement changed (a
+   * column move) and no structural mutation of the authored settings is needed.
+   *
+   * Collapse is re-attached by authored group identity (not visual column index, which the move just
+   * changed): a group that stayed contiguous is re-collapsed at its new position; a group split apart
+   * by the move auto-expands (its collapse is dropped), since a non-contiguous group cannot stay
+   * collapsed coherently.
+   */ rebuildState() {
+        const collapsedGroups = _class_private_method_get(this, _snapshotCollapsedGroups, snapshotCollapsedGroups).call(this);
+        _class_private_method_get(this, _deriveTree, deriveTree).call(this);
+        _class_private_method_get(this, _deriveVisibility, deriveVisibility).call(this);
+        _class_private_method_get(this, _reapplyCollapsedGroupsByIdentity, reapplyCollapsedGroupsByIdentity).call(this, collapsedGroups);
+        _class_private_method_get(this, _applySyncVisibility, applySyncVisibility).call(this);
+    }
+    /**
    * Merges settings with current plugin state.
    *
    * @param {object[]} settings An array of objects to merge with the current source settings.
@@ -147,30 +245,51 @@ class StateManager {
         _class_private_method_get(this, _rebuildPreservingCollapse, rebuildPreservingCollapse).call(this, ()=>_class_private_field_get(this, _sourceSettings).map(callback), (columnIndex)=>columnIndex);
     }
     /**
-   * Inserts `amount` columns into the source settings at the visual `columnIndex`, then rebuilds
-   * the tree and re-derives visibility. Headers spanning the insertion point are extended; columns
-   * inserted at a header boundary become standalone headers.
+   * Inserts `amount` columns into the source settings, then rebuilds the tree and re-derives
+   * visibility. Headers spanning the insertion point are extended; columns inserted at a header
+   * boundary become standalone headers.
+   *
+   * The authored source settings are keyed by physical column, while the collapsed state is keyed by
+   * visual column - so the insertion takes both indexes. They are equal when no column move is active;
+   * after a move they differ, and using each in its own space keeps headers and collapse aligned.
    *
-   * @param {number} columnIndex A visual column index at which the new columns are inserted.
+   * @param {number} visualColumnIndex The visual index the columns were inserted at (collapse space).
+   * @param {number} physicalColumnIndex The physical index the columns were inserted at (source space).
    * @param {number} amount The number of columns to insert.
-   */ insertColumns(columnIndex, amount) {
-        _class_private_method_get(this, _rebuildPreservingCollapse, rebuildPreservingCollapse).call(this, ()=>_class_private_field_get(this, _sourceSettings).insertColumns(columnIndex, amount), (c)=>c >= columnIndex ? c + amount : c);
+   */ insertColumns(visualColumnIndex, physicalColumnIndex, amount) {
+        // An index-shifting structural change invalidates move-driven membership overrides (keyed by
+        // physical column, with owner identities indexing the authored structure - both shifted here).
+        _class_private_method_get(this, _resetMembershipOverrides, resetMembershipOverrides).call(this);
+        _class_private_method_get(this, _rebuildPreservingCollapse, rebuildPreservingCollapse).call(this, ()=>_class_private_field_get(this, _sourceSettings).insertColumns(physicalColumnIndex, amount), (c)=>c >= visualColumnIndex ? c + amount : c);
     }
     /**
-   * Removes `amount` columns from the source settings starting at the visual `columnIndex`, then
-   * rebuilds the tree and re-derives visibility. Headers overlapping the removed range are shrunk,
-   * re-anchored, or dropped when they lose all their columns.
-   *
-   * @param {number} columnIndex A visual column index from which the columns are removed.
-   * @param {number} amount The number of columns to remove.
-   */ removeColumns(columnIndex, amount) {
-        const endIndex = columnIndex + amount;
-        _class_private_method_get(this, _rebuildPreservingCollapse, rebuildPreservingCollapse).call(this, ()=>_class_private_field_get(this, _sourceSettings).removeColumns(columnIndex, amount), (c)=>{
-            if (c < columnIndex) {
+   * Removes the given columns from the source settings, then rebuilds the tree and re-derives
+   * visibility. Headers overlapping the removed columns are shrunk, re-anchored, or dropped when they
+   * lose all their columns.
+   *
+   * The removed columns are identified by physical index (authored source settings are physical-keyed)
+   * and may be non-contiguous after a column move; they are removed highest-index-first so the lower
+   * indexes stay valid. The collapsed state is shifted in visual space, which an insert/remove always
+   * changes the same way regardless of any active move.
+   *
+   * @param {number} visualColumnIndex The visual index the columns were removed from (collapse space).
+   * @param {number} amount The number of columns removed (length of `physicalColumns`).
+   * @param {number[]} physicalColumns The physical indexes of the removed columns (source space).
+   */ removeColumns(visualColumnIndex, amount, physicalColumns) {
+        const endIndex = visualColumnIndex + amount;
+        // An index-shifting structural change invalidates move-driven membership overrides (keyed by
+        // physical column, with owner identities indexing the authored structure - both shifted here).
+        _class_private_method_get(this, _resetMembershipOverrides, resetMembershipOverrides).call(this);
+        _class_private_method_get(this, _rebuildPreservingCollapse, rebuildPreservingCollapse).call(this, ()=>{
+            [
+                ...physicalColumns
+            ].sort((a, b)=>b - a).forEach((physicalColumn)=>_class_private_field_get(this, _sourceSettings).removeColumns(physicalColumn, 1));
+        }, (c)=>{
+            if (c < visualColumnIndex) {
                 return c;
             }
             // The anchor column was removed but the group may survive - re-anchor to the range start.
-            return c >= endIndex ? c - amount : columnIndex;
+            return c >= endIndex ? c - amount : visualColumnIndex;
         });
     }
     /**
@@ -179,15 +298,18 @@ class StateManager {
    * @param {Function} callback A function that is called for every tree node.
    * @returns {Array}
    */ mapNodes(callback) {
-        return arrayReduce(_class_private_field_get(this, _headersTree).getRoots(), (acc, rootNode)=>{
+        const results = [];
+        // getRoots() returns TreeNode<HeaderNodeData>, so node.data is already HeaderNodeData here - the
+        // previous `as TreeNode`/`as unknown[]` casts only threw that type away. Walk and collect directly.
+        _class_private_field_get(this, _headersTree).getRoots().forEach((rootNode)=>{
             rootNode.walkDown((node)=>{
                 const result = callback(node.data);
                 if (result !== undefined) {
-                    acc.push(result);
+                    results.push(result);
                 }
             });
-            return acc;
-        }, []);
+        });
+        return results;
     }
     /**
    * Triggers an action from the NodeModifiers module.
@@ -197,16 +319,11 @@ class StateManager {
    * @param {number} columnIndex A visual column index.
    * @returns {object|undefined}
    */ triggerNodeModification(action, headerLevel, columnIndex) {
-        if (headerLevel < 0) {
-            headerLevel = this.rowCoordsToLevel(headerLevel) ?? 0;
-        }
-        const nodeToProcess = _class_private_field_get(this, _headersTree).getNode(headerLevel, columnIndex);
-        let actionResult;
-        if (nodeToProcess) {
-            actionResult = triggerNodeModification(action, nodeToProcess, columnIndex);
+        const { actionResult, modified } = _class_private_method_get(this, _applyNodeModification, applyNodeModification).call(this, action, headerLevel, columnIndex);
+        if (modified) {
             _class_private_field_set(this, _stateMatrix, generateMatrix(_class_private_field_get(this, _headersTree).getRoots()));
         }
-        return actionResult ?? undefined;
+        return actionResult;
     }
     /**
    * Triggers an action from the NodeModifiers module starting from the lowest header.
@@ -229,6 +346,91 @@ class StateManager {
         _class_private_field_set(this, _stateMatrix, generateMatrix(_class_private_field_get(this, _headersTree).getRoots()));
     }
     /**
+   * Re-parents the moved columns after a column move, recording membership overrides the derive uses
+   * to keep `columnDropMode: 'adopt'` groups cohesive. Call before `rebuildState()`.
+   *
+   * For each moved column the deepest group level at which it was dropped strictly inside a cohesive
+   * group is found first. From that level outward the column joins that group's ancestor chain (the
+   * group the column visually sits inside at each enclosing level), so a splitting ancestor grows
+   * to contain the adopted column instead of the inner run straddling its boundary. At every other
+   * level (deeper than the adoption, or none found) the column keeps its group when still beside a
+   * sibling, else goes standalone. The decisions are taken from the pre-update layout, then applied,
+   * so a whole group moved together (each member adjacent to a sibling) stays intact.
+   *
+   * @param {number[]} movedVisualColumns - The post-move visual indexes of the columns that moved.
+   */ reparentColumns(movedVisualColumns) {
+        const arrangement = _class_private_field_get(this, _columnArrangement) ?? createIdentityColumnArrangement();
+        const authoredLayers = _class_private_field_get(this, _sourceSettings).getData();
+        const layersCount = authoredLayers.length;
+        const columnsCount = layersCount > 0 ? authoredLayers[0].length : 0;
+        if (layersCount <= 1 || columnsCount === 0) {
+            return; // a single header level is all leaves - nothing to re-parent
+        }
+        const ownerIndexByLevel = authoredLayers.map((layer)=>computeOwnerIndex(layer));
+        // Effective owner = the move override if any, else the authored owner (see resolveOwnerKey).
+        const effectiveOwnerAt = (visualColumn, level)=>{
+            const physical = arrangement.getPhysicalFromVisual(visualColumn);
+            return resolveOwnerKey(physical, ownerIndexByLevel[level], _class_private_field_get(this, _membershipOverrides).get(physical)?.get(level));
+        };
+        // Authored owner ignores any override - the group the column belongs to in the authored config.
+        const authoredOwnerAt = (visualColumn, level)=>{
+            const physical = arrangement.getPhysicalFromVisual(visualColumn);
+            return resolveOwnerKey(physical, ownerIndexByLevel[level]);
+        };
+        // The columns moved together in this operation. Their mutual adjacency must be skipped when
+        // looking for the group a moved column sits inside, so a whole group dropped into another cohesive
+        // group is adopted as a block (each member's neighbor toward the block is a fellow moved column,
+        // not the surrounding group).
+        const movedSet = new Set(movedVisualColumns);
+        // The effective owner shared by the columns flanking the moved block at a level (the group the
+        // block sits strictly inside), or -1 when they differ or the block sits at an edge. Fellow moved
+        // columns are stepped over so the whole block is judged against the columns surrounding it.
+        const enclosingOwnerAt = (visualColumn, level)=>{
+            let left = visualColumn - 1;
+            let right = visualColumn + 1;
+            while(left >= 0 && movedSet.has(left)){
+                left -= 1;
+            }
+            while(right < columnsCount && movedSet.has(right)){
+                right += 1;
+            }
+            if (left < 0 || right >= columnsCount) {
+                return -1;
+            }
+            const leftOwner = effectiveOwnerAt(left, level);
+            return leftOwner === effectiveOwnerAt(right, level) && leftOwner >= 0 ? leftOwner : -1;
+        };
+        // Decide from the current layout first, then apply, so moved siblings see each other's old owner.
+        const decisions = [];
+        movedVisualColumns.forEach((visualColumn)=>{
+            const physical = arrangement.getPhysicalFromVisual(visualColumn);
+            // Deepest level at which the column was dropped strictly inside a cohesive group. The adoption
+            // there propagates outward through the group's ancestors (see #adoptedAncestorOwner).
+            let adoptionLevel = -1;
+            for(let level = 0; level < layersCount - 1; level++){
+                const enclosing = enclosingOwnerAt(visualColumn, level);
+                if (enclosing >= 0 && authoredLayers[level][enclosing]?.columnDropMode !== 'split') {
+                    adoptionLevel = level;
+                }
+            }
+            for(let level = 0; level < layersCount - 1; level++){
+                const authoredOwner = authoredOwnerAt(visualColumn, level);
+                // At or inside the adoption level the column joins the cohesive group's ancestor chain;
+                // anywhere else it reverts to its authored owner, so a column moved out of a group keeps its
+                // own ancestor labels and the group renders a same-label banner over each contiguous run.
+                const target = level <= adoptionLevel ? _class_private_method_get(this, _adoptedAncestorOwner, adoptedAncestorOwner).call(this, visualColumn, level, enclosingOwnerAt, authoredOwnerAt, ownerIndexByLevel) : authoredOwner;
+                decisions.push({
+                    physical,
+                    level,
+                    identity: target === authoredOwner ? null : target
+                });
+            }
+        });
+        decisions.forEach(({ physical, level, identity })=>{
+            _class_private_method_get(this, _setMembershipOverride, setMembershipOverride).call(this, physical, level, identity);
+        });
+    }
+    /**
    * @memberof StateManager#
    * @function rowCoordsToLevel
    *
@@ -405,11 +607,13 @@ class StateManager {
         return _class_private_field_get(this, _sourceSettings).getLayersCount();
     }
     /**
-   * Gets a total number of columns count.
+   * Gets the number of columns the rendered header structure spans (the visual width). This reads
+   * the derived settings, so it matches the generated matrix and the current column arrangement.
+   * With an identity arrangement it equals the authored column count.
    *
    * @returns {number}
    */ getColumnsCount() {
-        return _class_private_field_get(this, _sourceSettings).getColumnsCount();
+        return _class_private_field_get(this, _derivedSettings).getColumnsCount();
     }
     /**
    * Computes the visual column indexes that should be hidden purely by the `visibleWhen` rules of
@@ -465,21 +669,54 @@ class StateManager {
         return columnsToHide;
     }
     /**
+   * Gets every currently collapsed group as its header level and the visual column span it covers
+   * (its left-edge visual column index and original colspan). Used to detect, before a column move,
+   * whether the move would split a collapsed group.
+   *
+   * @returns {Array<{headerLevel: number, columnIndex: number, origColspan: number}>}
+   */ getCollapsedGroups() {
+        const groups = [];
+        _class_private_field_get(this, _headersTree).getRoots().forEach((rootNode)=>{
+            rootNode.walkDown((node)=>{
+                const { isCollapsed, headerLevel, columnIndex, origColspan } = node.data;
+                if (isCollapsed) {
+                    groups.push({
+                        headerLevel,
+                        columnIndex,
+                        origColspan
+                    });
+                }
+            });
+        });
+        return groups;
+    }
+    /**
    * Clears the column state manager to the initial state.
    */ clear() {
         _class_private_field_set(this, _stateMatrix, []);
         _class_private_field_get(this, _sourceSettings).clear();
+        _class_private_field_get(this, _derivedSettings).clear();
         _class_private_field_get(this, _headersTree).clear();
         _class_private_field_set(this, _lastColumnVisibility, null);
+        _class_private_field_set(this, _membershipOverrides, new Map());
     }
     constructor(){
+        _class_private_method_init(this, _snapshotCollapsedGroups);
+        _class_private_method_init(this, _reapplyCollapsedGroupsByIdentity);
+        _class_private_method_init(this, _findNodesByAuthoredIdentity);
         _class_private_method_init(this, _rebuildPreservingCollapse);
         _class_private_method_init(this, _snapshotCollapsedNodes);
         _class_private_method_init(this, _reapplyCollapsedNodes);
+        _class_private_method_init(this, _applyNodeModification);
         _class_private_method_init(this, _applySyncVisibility);
         _class_private_method_init(this, _deriveVisibility);
+        _class_private_method_init(this, _deriveTree);
+        _class_private_method_init(this, _adoptedAncestorOwner);
+        _class_private_method_init(this, _resetMembershipOverrides);
+        _class_private_method_init(this, _setMembershipOverride);
         /**
-   * The instance of the source settings class.
+   * The authored (physical-order) source settings - the normalized user configuration. All
+   * structural mutations (setData, mergeWith, map, insertColumns, removeColumns) operate on this.
    *
    * @private
    * @type {SourceSettings}
@@ -488,6 +725,17 @@ class StateManager {
             value: void 0
         });
         /**
+   * Visual-order settings derived from #sourceSettings through deriveVisualSettings(). The headers
+   * tree is built from these, so the rendered structure follows the current column arrangement. With
+   * an identity arrangement they equal the authored settings, so the built tree is unchanged.
+   *
+   * @private
+   * @type {SourceSettings}
+   */ _class_private_field_init(this, _derivedSettings, {
+            writable: true,
+            value: void 0
+        });
+        /**
    * The instance of the headers tree.
    *
    * @private
@@ -504,18 +752,64 @@ class StateManager {
             writable: true,
             value: void 0
         });
+        _class_private_field_init(this, _columnArrangement, {
+            writable: true,
+            value: void 0
+        });
+        _class_private_field_init(this, _membershipOverrides, {
+            writable: true,
+            value: void 0
+        });
         _class_private_field_set(this, _sourceSettings, new SourceSettings());
-        _class_private_field_set(this, _headersTree, new HeadersTree(_class_private_field_get(this, _sourceSettings)));
+        _class_private_field_set(this, _derivedSettings, new SourceSettings());
+        _class_private_field_set(this, _headersTree, new HeadersTree(_class_private_field_get(this, _derivedSettings)));
         _class_private_field_set(this, _stateMatrix, [
             []
         ]);
         _class_private_field_set(this, _lastColumnVisibility, null);
+        _class_private_field_set(this, _columnArrangement, null);
+        _class_private_field_set(this, _membershipOverrides, new Map());
     }
 }
+function snapshotCollapsedGroups() {
+    const groups = [];
+    _class_private_field_get(this, _headersTree).getRoots().forEach((rootNode)=>{
+        rootNode.walkDown((node)=>{
+            const { isCollapsed, headerLevel, authoredColumnIndex } = node.data;
+            if (isCollapsed && typeof authoredColumnIndex === 'number' && authoredColumnIndex >= 0) {
+                groups.push({
+                    headerLevel,
+                    authoredColumnIndex
+                });
+            }
+        });
+    });
+    return groups;
+}
+function reapplyCollapsedGroupsByIdentity(collapsedGroups) {
+    collapsedGroups.forEach(({ headerLevel, authoredColumnIndex })=>{
+        const matches = _class_private_method_get(this, _findNodesByAuthoredIdentity, findNodesByAuthoredIdentity).call(this, headerLevel, authoredColumnIndex);
+        if (matches.length === 1) {
+            // Matrix-free: the trailing #applySyncVisibility regenerates the matrix once for all groups.
+            _class_private_method_get(this, _applyNodeModification, applyNodeModification).call(this, 'collapse', headerLevel, matches[0].data.columnIndex);
+        }
+    });
+}
+function findNodesByAuthoredIdentity(headerLevel, authoredColumnIndex) {
+    const matches = [];
+    _class_private_field_get(this, _headersTree).getRoots().forEach((rootNode)=>{
+        rootNode.walkDown((node)=>{
+            if (node.data.headerLevel === headerLevel && node.data.authoredColumnIndex === authoredColumnIndex) {
+                matches.push(node);
+            }
+        });
+    });
+    return matches;
+}
 function rebuildPreservingCollapse(mutate, shiftColumnIndex) {
     const collapsedNodes = _class_private_method_get(this, _snapshotCollapsedNodes, snapshotCollapsedNodes).call(this);
     mutate();
-    _class_private_field_get(this, _headersTree).buildTree();
+    _class_private_method_get(this, _deriveTree, deriveTree).call(this);
     // Derive visibility before re-collapsing, but skip the matrix here - #reapplyCollapsedNodes
     // reads the tree (not the matrix) and the trailing #applySyncVisibility regenerates it once,
     // so building the matrix at this point would only be discarded work.
@@ -540,9 +834,26 @@ function snapshotCollapsedNodes() {
 }
 function reapplyCollapsedNodes(collapsedNodes, shiftColumnIndex) {
     collapsedNodes.forEach(({ headerLevel, columnIndex })=>{
-        this.triggerNodeModification('collapse', headerLevel, shiftColumnIndex(columnIndex));
+        // Matrix-free: the trailing #applySyncVisibility regenerates the matrix once for all nodes.
+        _class_private_method_get(this, _applyNodeModification, applyNodeModification).call(this, 'collapse', headerLevel, shiftColumnIndex(columnIndex));
     });
 }
+function applyNodeModification(action, headerLevel, columnIndex) {
+    if (headerLevel < 0) {
+        headerLevel = this.rowCoordsToLevel(headerLevel) ?? 0;
+    }
+    const nodeToProcess = _class_private_field_get(this, _headersTree).getNode(headerLevel, columnIndex);
+    if (!nodeToProcess) {
+        return {
+            actionResult: undefined,
+            modified: false
+        };
+    }
+    return {
+        actionResult: triggerNodeModification(action, nodeToProcess, columnIndex) ?? undefined,
+        modified: true
+    };
+}
 function applySyncVisibility() {
     _class_private_method_get(this, _deriveVisibility, deriveVisibility).call(this);
     _class_private_field_set(this, _stateMatrix, generateMatrix(_class_private_field_get(this, _headersTree).getRoots()));
@@ -552,6 +863,38 @@ function deriveVisibility() {
         syncVisibilityOnTree(_class_private_field_get(this, _headersTree).getRoots(), _class_private_field_get(this, _lastColumnVisibility));
     }
 }
+function deriveTree() {
+    const arrangement = _class_private_field_get(this, _columnArrangement) ?? createIdentityColumnArrangement();
+    _class_private_field_get(this, _derivedSettings).setNormalizedData(deriveVisualSettings(_class_private_field_get(this, _sourceSettings).getData(), arrangement, _class_private_field_get(this, _membershipOverrides)));
+    _class_private_field_get(this, _headersTree).buildTree();
+}
+function adoptedAncestorOwner(visualColumn, level, enclosingOwnerAt, authoredOwnerAt, ownerIndexByLevel) {
+    const enclosing = enclosingOwnerAt(visualColumn, level);
+    if (enclosing >= 0) {
+        return enclosing;
+    }
+    // The neighbors disagree at this enclosing level; fall back to the authored ancestor of the group
+    // the column sits inside one level deeper, which is a valid (properly nested) parent.
+    const innerOwner = enclosingOwnerAt(visualColumn, level + 1);
+    return innerOwner >= 0 ? ownerIndexByLevel[level][innerOwner] : authoredOwnerAt(visualColumn, level);
+}
+function resetMembershipOverrides() {
+    _class_private_field_set(this, _membershipOverrides, new Map());
+}
+function setMembershipOverride(physical, level, identity) {
+    if (identity === null) {
+        const levels = _class_private_field_get(this, _membershipOverrides).get(physical);
+        levels?.delete(level);
+        if (levels?.size === 0) {
+            _class_private_field_get(this, _membershipOverrides).delete(physical);
+        }
+        return;
+    }
+    if (!_class_private_field_get(this, _membershipOverrides).has(physical)) {
+        _class_private_field_get(this, _membershipOverrides).set(physical, new Map());
+    }
+    _class_private_field_get(this, _membershipOverrides).get(physical).set(level, identity);
+}
 /**
  * The state manager is a source of truth for nested headers configuration.
  *

package/plugins/nestedHeaders/stateManager/matrixGenerator.js

@@ -72,8 +72,9 @@ function generateMatrix(headerRoots) {
  * @param {object} nodeData The tree data object.
  * @returns {object}
  */ function createHeaderSettings(nodeData) {
-    // For the matrix module we do not need to export "crossHiddenColumns" key. It's redundant here.
-    const { crossHiddenColumns, ...headerRootSettings } = (0, _utils.createDefaultHeaderSettings)(nodeData);
+    // The matrix module does not need the "crossHiddenColumns" or "columnDropMode" keys - the former is
+    // a visibility detail, the latter a structural input that only affects how the tree is derived.
+    const { crossHiddenColumns, columnDropMode, ...headerRootSettings } = (0, _utils.createDefaultHeaderSettings)(nodeData);
     return headerRootSettings;
 }
 /**

package/plugins/nestedHeaders/stateManager/matrixGenerator.mjs

@@ -91,8 +91,9 @@ import { createDefaultHeaderSettings, createPlaceholderHeaderSettings } from './
  * @param {object} nodeData The tree data object.
  * @returns {object}
  */ function createHeaderSettings(nodeData) {
-    // For the matrix module we do not need to export "crossHiddenColumns" key. It's redundant here.
-    const { crossHiddenColumns, ...headerRootSettings } = createDefaultHeaderSettings(nodeData);
+    // The matrix module does not need the "crossHiddenColumns" or "columnDropMode" keys - the former is
+    // a visibility detail, the latter a structural input that only affects how the tree is derived.
+    const { crossHiddenColumns, columnDropMode, ...headerRootSettings } = createDefaultHeaderSettings(nodeData);
     return headerRootSettings;
 }
 /**

package/plugins/nestedHeaders/stateManager/settingsNormalizer.js

@@ -48,7 +48,7 @@ function normalizeSettings(sourceSettings, columnsLimit = Infinity) {
    */ const normalizeHeaderSettings = (sourceHeaderSettings)=>{
         const headerSettings = (0, _utils.createDefaultHeaderSettings)();
         if ((0, _object.isObject)(sourceHeaderSettings)) {
-            const { label, colspan, rowspan, headerClassName, visibleWhen } = sourceHeaderSettings;
+            const { label, colspan, rowspan, headerClassName, visibleWhen, columnDropMode } = sourceHeaderSettings;
             headerSettings.label = (0, _mixed.stringify)(label);
             if (typeof colspan === 'number' && colspan > 1) {
                 headerSettings.colspan = colspan;
@@ -69,6 +69,10 @@ function normalizeSettings(sourceSettings, columnsLimit = Infinity) {
             if (typeof visibleWhen === 'string' && VISIBLE_WHEN_VALUES.includes(visibleWhen)) {
                 headerSettings.visibleWhen = visibleWhen;
             }
+            // Only `'split'` enables splitting; any other (or unset) value keeps the adopt default.
+            if (columnDropMode === 'split') {
+                headerSettings.columnDropMode = 'split';
+            }
         } else {
             headerSettings.label = (0, _mixed.stringify)(sourceHeaderSettings);
         }

package/plugins/nestedHeaders/stateManager/settingsNormalizer.mjs

@@ -75,7 +75,7 @@ const VISIBLE_WHEN_VALUES = [
    */ const normalizeHeaderSettings = (sourceHeaderSettings)=>{
         const headerSettings = createDefaultHeaderSettings();
         if (isObject(sourceHeaderSettings)) {
-            const { label, colspan, rowspan, headerClassName, visibleWhen } = sourceHeaderSettings;
+            const { label, colspan, rowspan, headerClassName, visibleWhen, columnDropMode } = sourceHeaderSettings;
             headerSettings.label = stringify(label);
             if (typeof colspan === 'number' && colspan > 1) {
                 headerSettings.colspan = colspan;
@@ -96,6 +96,10 @@ const VISIBLE_WHEN_VALUES = [
             if (typeof visibleWhen === 'string' && VISIBLE_WHEN_VALUES.includes(visibleWhen)) {
                 headerSettings.visibleWhen = visibleWhen;
             }
+            // Only `'split'` enables splitting; any other (or unset) value keeps the adopt default.
+            if (columnDropMode === 'split') {
+                headerSettings.columnDropMode = 'split';
+            }
         } else {
             headerSettings.label = stringify(sourceHeaderSettings);
         }