handsontable 18.0.0 → 18.1.0-rc1

package/plugins/nestedRows/nestedRows.mjs

@@ -4,15 +4,12 @@ function _check_private_redeclaration(obj, privateCollection) {
     }
 }
 function _class_apply_descriptor_get(receiver, descriptor) {
-    if (descriptor.get) {
-        return descriptor.get.call(receiver);
-    }
+    if (descriptor.get) return descriptor.get.call(receiver);
     return descriptor.value;
 }
 function _class_apply_descriptor_set(receiver, descriptor, value) {
-    if (descriptor.set) {
-        descriptor.set.call(receiver, value);
-    } else {
+    if (descriptor.set) descriptor.set.call(receiver, value);
+    else {
         if (!descriptor.writable) {
             throw new TypeError("attempted to set read only private field");
         }
@@ -20,9 +17,7 @@ function _class_apply_descriptor_set(receiver, descriptor, value) {
     }
 }
 function _class_extract_field_descriptor(receiver, privateMap, action) {
-    if (!privateMap.has(receiver)) {
-        throw new TypeError("attempted to " + action + " private field on non-instance");
-    }
+    if (!privateMap.has(receiver)) throw new TypeError("attempted to " + action + " private field on non-instance");
     return privateMap.get(receiver);
 }
 function _class_private_field_get(receiver, privateMap) {
@@ -38,6 +33,14 @@ function _class_private_field_set(receiver, privateMap, value) {
     _class_apply_descriptor_set(receiver, descriptor, value);
     return value;
 }
+function _class_private_method_get(receiver, privateSet, fn) {
+    if (!privateSet.has(receiver)) throw new TypeError("attempted to get private field on non-instance");
+    return fn;
+}
+function _class_private_method_init(obj, privateSet) {
+    _check_private_redeclaration(obj, privateSet);
+    privateSet.add(obj);
+}
 import { BasePlugin } from '../base/index.mjs';
 import DataManager from './data/dataManager.mjs';
 import CollapsingUI from './ui/collapsing.mjs';
@@ -45,7 +48,6 @@ import HeadersUI from './ui/headers.mjs';
 import ContextMenuUI from './ui/contextMenu.mjs';
 import { isValidDataSource } from './utils/isValidDataSource.mjs';
 import { error } from '../../helpers/console.mjs';
-import { TrimmingMap } from '../../translations/index.mjs';
 import { EDITOR_EDIT_GROUP as SHORTCUTS_GROUP_EDITOR } from '../../shortcuts/contexts/index.mjs';
 import RowMoveController from './utils/rowMoveController.mjs';
 export const PLUGIN_KEY = 'nestedRows';
@@ -67,6 +69,40 @@ var /**
    *
    * @type {boolean}
    */ _isFirstRender = /*#__PURE__*/ new WeakMap(), /**
+   * Walks the nested structure depth-first and calls back for every row that has children.
+   *
+   * @param {Array} nodes Row objects to walk.
+   * @param {Function} callback Receives the physical row index and the nesting level.
+   * @param {number} [level=0] The nesting level of `nodes`.
+   */ _eachParent = /*#__PURE__*/ new WeakSet(), /**
+   * Tells whether the plugin can act on the grid right now.
+   *
+   * `disablePlugin()` unregisters the `nestedRows` index map but leaves `collapsingUI` and
+   * `collapsedRowsMap` in place, so a write to the map afterwards is silently dropped. Without this
+   * check the public methods would report a state change that never reached the grid.
+   *
+   * @returns {boolean}
+   */ _isOperational = /*#__PURE__*/ new WeakSet(), /**
+   * Translates a visual row index into a physical one.
+   *
+   * @param {number} row Visual row index.
+   * @returns {number|null} `null` when the argument is not a valid, existing visual row.
+   */ _toPhysicalRow = /*#__PURE__*/ new WeakSet(), /**
+   * Translates a visual row index into a physical one, for the methods that act on a parent row.
+   *
+   * Returns `null` when the plugin is not ready, so the caller can bail out before reaching the
+   * CollapsingUI. Whether the row is really a parent is decided by the CollapsingUI, which reports it
+   * through the hooks.
+   *
+   * @param {number} row Visual row index.
+   * @returns {number|null}
+   */ _toPhysicalParentRow = /*#__PURE__*/ new WeakSet(), /**
+   * Collapses or expands a single parent, addressed by its visual row index.
+   *
+   * @param {number} row Visual row index of the parent.
+   * @param {string} action Either `'collapse'` or `'expand'`.
+   * @returns {boolean} `true` if the collapsed state changed.
+   */ _toggleParentAt = /*#__PURE__*/ new WeakSet(), /**
    * `beforeRowMove` hook callback.
    *
    * @param {Array} rows Array of visual row indexes to be moved.
@@ -184,7 +220,7 @@ var /**
         if (this.enabled) {
             return;
         }
-        this.collapsedRowsMap = this.hot.rowIndexMapper.registerMap('nestedRows', new TrimmingMap());
+        this.collapsedRowsMap = this.hot.rowIndexMapper.createAndRegisterIndexMap('nestedRows', 'trimming');
         this.dataManager = new DataManager(this, this.hot);
         this.collapsingUI = new CollapsingUI(this, this.hot);
         this.headersUI = new HeadersUI(this, this.hot);
@@ -227,12 +263,22 @@ var /**
    * This method is executed when [`updateSettings()`](@/api/core.md#updatesettings) is invoked with any of the following configuration options:
    *  - [`nestedRows`](@/api/options.md#nestedrows)
    */ updatePlugin() {
+        // `disablePlugin` unregisters the trimming map and `enablePlugin` builds a brand new CollapsingUI,
+        // so the collapsed state has to be copied out before the teardown and replayed afterwards.
+        // Without this every `updateSettings` call that carries the `nestedRows` key expands the grid -
+        // which, in React, is every parent re-render.
+        const collapsedParents = this.collapsingUI?.getCollapsedParents() ?? [];
         this.disablePlugin();
         // We store a state of the data manager.
         const currentSourceData = this.dataManager.getData();
         this.enablePlugin();
         // After enabling plugin previously stored data is restored.
         this.dataManager.updateWithData(currentSourceData);
+        if (collapsedParents.length > 0) {
+            // Replaying a state the user already chose is not a new action, so the hooks stay silent. Firing
+            // them here would report a collapse on every settings update.
+            this.collapsingUI.toggleCollapsedRows(collapsedParents, 'collapse', false);
+        }
         super.updatePlugin();
     }
     /**
@@ -253,11 +299,9 @@ var /**
                 }
                 const { highlight } = activeRange;
                 const row = this.collapsingUI.translateTrimmedRow(highlight.row ?? 0);
-                if (this.collapsingUI.areChildrenCollapsed(row)) {
-                    this.collapsingUI.expandChildren(row);
-                } else {
-                    this.collapsingUI.collapseChildren(row);
-                }
+                this.collapsingUI.toggleCollapsedRows([
+                    row
+                ], this.collapsingUI.areChildrenCollapsed(row) ? 'expand' : 'collapse');
                 // prevent default Enter behavior (move to the next row within a selection range)
                 return false;
             },
@@ -278,6 +322,243 @@ var /**
         this.hot.getShortcutManager().getContext('grid')?.removeShortcutsByGroup(SHORTCUTS_GROUP);
     }
     /**
+   * Collapses every top-level parent row, which hides all of their descendants.
+   *
+   * A parent that was already collapsed inside another one stays collapsed.
+   *
+   * @fires Hooks#beforeRowCollapse
+   * @fires Hooks#afterRowCollapse
+   */ collapseAll() {
+        if (!_class_private_method_get(this, _isOperational, isOperational).call(this)) {
+            return;
+        }
+        this.collapsingUI.collapseAll();
+    }
+    /**
+   * Expands every collapsed parent row at every nesting level, so no row stays hidden.
+   *
+   * @fires Hooks#beforeRowExpand
+   * @fires Hooks#afterRowExpand
+   */ expandAll() {
+        if (!_class_private_method_get(this, _isOperational, isOperational).call(this)) {
+            return;
+        }
+        this.collapsingUI.toggleCollapsedRows(this.collapsingUI.getCollapsedParentsShallowestFirst(), 'expand');
+    }
+    /**
+   * Collapses a parent row, which hides its children.
+   *
+   * @param {number} row Visual row index of the parent.
+   * @returns {boolean} `true` if the collapsed state changed. `false` when the row is not a parent,
+   * when it is already collapsed, or when the {@link Hooks#beforeRowCollapse} hook blocked the action.
+   * @fires Hooks#beforeRowCollapse
+   * @fires Hooks#afterRowCollapse
+   */ collapseParent(row) {
+        return _class_private_method_get(this, _toggleParentAt, toggleParentAt).call(this, row, 'collapse');
+    }
+    /**
+   * Expands a parent row, which shows its children again.
+   *
+   * @param {number} row Visual row index of the parent.
+   * @returns {boolean} `true` if the collapsed state changed. `false` when the row is not a parent,
+   * when it is already expanded, or when the {@link Hooks#beforeRowExpand} hook blocked the action.
+   * @fires Hooks#beforeRowExpand
+   * @fires Hooks#afterRowExpand
+   */ expandParent(row) {
+        return _class_private_method_get(this, _toggleParentAt, toggleParentAt).call(this, row, 'expand');
+    }
+    /**
+   * Collapses an expanded parent row, or expands a collapsed one. This is the same action as clicking
+   * the button in the row header or pressing Enter on it.
+   *
+   * @param {number} row Visual row index of the parent.
+   * @returns {boolean} `true` if the collapsed state changed.
+   * @fires Hooks#beforeRowCollapse
+   * @fires Hooks#afterRowCollapse
+   * @fires Hooks#beforeRowExpand
+   * @fires Hooks#afterRowExpand
+   */ toggleParent(row) {
+        const physicalRow = _class_private_method_get(this, _toPhysicalParentRow, toPhysicalParentRow).call(this, row);
+        if (physicalRow === null) {
+            return false;
+        }
+        const isCollapsed = this.dataManager.isParent(physicalRow) && this.collapsingUI.areChildrenCollapsed(physicalRow);
+        return this.collapsingUI.toggleCollapsedRows([
+            physicalRow
+        ], isCollapsed ? 'expand' : 'collapse');
+    }
+    /**
+   * Returns the physical row indexes of every parent row that is collapsed.
+   *
+   * The indexes are physical, not visual, because a parent collapsed inside another collapsed parent
+   * is trimmed and therefore has no visual index at all. Physical indexes are also what you want to
+   * store when saving the state. Convert one with {@link Core#toVisualRow}.
+   *
+   * @returns {number[]} Physical row indexes, sorted ascending.
+   */ getCollapsedParents() {
+        if (!_class_private_method_get(this, _isOperational, isOperational).call(this)) {
+            return [];
+        }
+        return this.collapsingUI.getCollapsedParents();
+    }
+    /**
+   * Checks whether a parent row is collapsed.
+   *
+   * @param {number} row Visual row index of the parent.
+   * @returns {boolean} `true` if the row is a parent and its children are hidden.
+   */ isParentCollapsed(row) {
+        const physicalRow = _class_private_method_get(this, _toPhysicalParentRow, toPhysicalParentRow).call(this, row);
+        // A row without children is never collapsed. The check matters because
+        // `areChildrenCollapsed` answers "are all children collapsed", which is vacuously `true`
+        // for a row that has none.
+        if (physicalRow === null || !this.dataManager.isParent(physicalRow)) {
+            return false;
+        }
+        return this.collapsingUI.areChildrenCollapsed(physicalRow);
+    }
+    /**
+   * Checks whether a row has children.
+   *
+   * @param {number} row Visual row index.
+   * @returns {boolean}
+   */ isParent(row) {
+        const physicalRow = _class_private_method_get(this, _toPhysicalRow, toPhysicalRow).call(this, row);
+        if (physicalRow === null) {
+            return false;
+        }
+        return this.dataManager.isParent(physicalRow);
+    }
+    /**
+   * Returns how deeply a row is nested. Top-level rows are at level `0`.
+   *
+   * @param {number} row Visual row index.
+   * @returns {number|null} The nesting level, or `null` when the row does not exist.
+   */ getRowLevel(row) {
+        const physicalRow = _class_private_method_get(this, _toPhysicalRow, toPhysicalRow).call(this, row);
+        if (physicalRow === null) {
+            return null;
+        }
+        return this.dataManager.getRowLevel(physicalRow);
+    }
+    /**
+   * Returns the parent of a row.
+   *
+   * A visible row always has visible ancestors, so the returned index is visual like the argument.
+   *
+   * @param {number} row Visual row index.
+   * @returns {number|null} Visual row index of the parent, or `null` for a top-level row.
+   */ getRowParent(row) {
+        const physicalRow = _class_private_method_get(this, _toPhysicalRow, toPhysicalRow).call(this, row);
+        if (physicalRow === null) {
+            return null;
+        }
+        const parentObject = this.dataManager.getRowParent(physicalRow);
+        const parentPhysicalRow = this.dataManager.getRowIndex(parentObject);
+        if (parentPhysicalRow === null) {
+            return null;
+        }
+        const parentVisualRow = this.hot.toVisualRow(parentPhysicalRow);
+        return parentVisualRow === null ? null : parentVisualRow;
+    }
+    /**
+   * Counts the children of a row.
+   *
+   * @param {number} row Visual row index.
+   * @param {boolean} [recursive=false] `true` counts every descendant, `false` counts only the direct
+   * children.
+   * @returns {number}
+   */ countChildren(row, recursive = false) {
+        const physicalRow = _class_private_method_get(this, _toPhysicalRow, toPhysicalRow).call(this, row);
+        if (physicalRow === null) {
+            return 0;
+        }
+        if (recursive) {
+            return this.dataManager.countChildren(physicalRow);
+        }
+        const rowObject = this.dataManager.getDataObject(physicalRow);
+        return (rowObject?.__children ?? []).length;
+    }
+    /**
+   * Expands every ancestor of a row, so that a row hidden inside collapsed parents becomes visible.
+   *
+   * Takes a physical row index, because the row you want to reveal is hidden and therefore has no
+   * visual index.
+   *
+   * @param {number} row Physical row index of the row to reveal.
+   * @returns {boolean} `true` if anything was expanded.
+   * @fires Hooks#beforeRowExpand
+   * @fires Hooks#afterRowExpand
+   */ expandToRow(row) {
+        if (!_class_private_method_get(this, _isOperational, isOperational).call(this) || !Number.isInteger(row) || row < 0) {
+            return false;
+        }
+        const collapsedAncestors = [];
+        let parentObject = this.dataManager.getRowParent(row);
+        while(parentObject !== null){
+            const parentRow = this.dataManager.getRowIndex(parentObject);
+            if (parentRow === null) {
+                break;
+            }
+            if (this.collapsingUI.getCollapsedParents().indexOf(parentRow) > -1) {
+                collapsedAncestors.push(parentRow);
+            }
+            parentObject = this.dataManager.getRowParent(parentObject);
+        }
+        if (collapsedAncestors.length === 0) {
+            return false;
+        }
+        // Shallowest first, so an ancestor is expanded before its own descendants.
+        return this.collapsingUI.toggleCollapsedRows(collapsedAncestors.reverse(), 'expand');
+    }
+    /**
+   * Shows rows down to the given nesting level and collapses everything deeper.
+   *
+   * Level `0` leaves only the top-level rows visible.
+   *
+   * This runs as two steps - an expand and a collapse - so it fires both pairs of hooks. Returning
+   * `false` from {@link Hooks#beforeRowExpand} cancels the whole call and leaves the grid as it was.
+   * Returning `false` from {@link Hooks#beforeRowCollapse} blocks only the collapse step, so the
+   * expand step stays applied.
+   *
+   * @param {number} level The deepest nesting level that stays expanded.
+   * @fires Hooks#beforeRowCollapse
+   * @fires Hooks#afterRowCollapse
+   * @fires Hooks#beforeRowExpand
+   * @fires Hooks#afterRowExpand
+   */ expandToLevel(level) {
+        if (!_class_private_method_get(this, _isOperational, isOperational).call(this) || !Number.isInteger(level) || level < 0) {
+            return;
+        }
+        const toCollapse = [];
+        const toExpand = [];
+        // `batch` suspends rendering as well as index-map recalculation. This runs two passes, and each
+        // one renders on its own, so without it the grid would render the intermediate state where the
+        // deeper rows are briefly untrimmed.
+        this.hot.batch(()=>{
+            const data = this.dataManager.getData() ?? [];
+            _class_private_method_get(this, _eachParent, eachParent).call(this, data, (parentRow, parentLevel)=>{
+                if (parentLevel >= level) {
+                    toCollapse.push(parentRow);
+                } else {
+                    toExpand.push(parentRow);
+                }
+            });
+            // Expand from the shallowest down, so each parent is reachable when its turn comes, then
+            // collapse from the deepest up.
+            //
+            // The expand pass is checked for a veto, not for `performed`: `performed` is also `false` when
+            // every shallower parent is already open, which is the common case and must not stop the
+            // collapse pass. A `beforeRowExpand` veto cancels the whole call, so the grid keeps the state it
+            // had. A veto on the collapse pass below leaves the expand applied - see the method's JSDoc.
+            if (toExpand.length > 0 && this.collapsingUI.applyCollapsedRowsChange(toExpand, 'expand').vetoed) {
+                return;
+            }
+            if (toCollapse.length > 0) {
+                this.collapsingUI.toggleCollapsedRows(toCollapse.reverse(), 'collapse');
+            }
+        });
+    }
+    /**
    * Enable the modify hook skipping flag - allows retrieving the data from Handsontable without this plugin's
    * modifications.
    *
@@ -336,7 +617,7 @@ var /**
         super.destroy();
     }
     constructor(...args){
-        super(...args), _class_private_field_init(this, _skipRender, {
+        super(...args), _class_private_method_init(this, _eachParent), _class_private_method_init(this, _isOperational), _class_private_method_init(this, _toPhysicalRow), _class_private_method_init(this, _toPhysicalParentRow), _class_private_method_init(this, _toggleParentAt), _class_private_field_init(this, _skipRender, {
             writable: true,
             value: void 0
         }), _class_private_field_init(this, _skipCoreAPIModifiers, {
@@ -519,3 +800,37 @@ var /**
         });
     }
 }
+function eachParent(nodes, callback, level = 0) {
+    nodes.forEach((node)=>{
+        if (!this.dataManager.hasChildren(node)) {
+            return;
+        }
+        const physicalRow = this.dataManager.getRowIndex(node);
+        if (physicalRow !== null) {
+            callback(physicalRow, level);
+        }
+        _class_private_method_get(this, _eachParent, eachParent).call(this, node.__children ?? [], callback, level + 1);
+    });
+}
+function isOperational() {
+    return this.enabled && !!this.dataManager && !!this.collapsingUI;
+}
+function toPhysicalRow(row) {
+    if (!_class_private_method_get(this, _isOperational, isOperational).call(this) || !Number.isInteger(row) || row < 0) {
+        return null;
+    }
+    const physicalRow = this.hot.toPhysicalRow(row);
+    return physicalRow === null || physicalRow === undefined ? null : physicalRow;
+}
+function toPhysicalParentRow(row) {
+    return _class_private_method_get(this, _toPhysicalRow, toPhysicalRow).call(this, row);
+}
+function toggleParentAt(row, action) {
+    const physicalRow = _class_private_method_get(this, _toPhysicalParentRow, toPhysicalParentRow).call(this, row);
+    if (physicalRow === null) {
+        return false;
+    }
+    return this.collapsingUI.toggleCollapsedRows([
+        physicalRow
+    ], action);
+}

package/plugins/nestedRows/ui/collapsing.d.ts

@@ -12,6 +12,7 @@ import type { RowObject } from '../data/dataManager';
  * @augments BaseUI
  */
 declare class CollapsingUI extends BaseUI {
+    #private;
     /**
      * Reference to the DataManager instance.
      *
@@ -129,14 +130,71 @@ declare class CollapsingUI extends BaseUI {
      * @param {boolean} [doTrimming=true] `true` if the rows should be untrimmed after finishing the function.
      */
     expandMultipleChildren(rows: number[] | RowObject[], forceRender?: boolean, doTrimming?: boolean): void;
+    /**
+     * Returns the physical indexes of the parent rows that are collapsed right now.
+     *
+     * The list is sorted ascending so hook payloads are stable and comparable between calls.
+     *
+     * @returns {number[]} Physical row indexes of collapsed parents.
+     */
+    getCollapsedParents(): number[];
+    /**
+     * Collapses or expands the given parent rows and fires the matching pair of hooks.
+     *
+     * This is the single choke point for every collapse and expand in the plugin - the row header
+     * button, the Enter shortcut, and the public plugin methods all run through it, so all of them
+     * produce the same state change and the same hooks.
+     *
+     * @param {number[]} parents Physical row indexes of the parents to act on.
+     * @param {string} action Either `'collapse'` or `'expand'`.
+     * @param {boolean} [shouldRunHooks=true] `false` skips both hooks - used when replaying state that the
+     * user already chose, such as restoring after an `updateSettings` call.
+     * @returns {boolean} `true` if the collapsed state actually changed.
+     * @fires Hooks#beforeRowCollapse
+     * @fires Hooks#afterRowCollapse
+     * @fires Hooks#beforeRowExpand
+     * @fires Hooks#afterRowExpand
+     */
+    toggleCollapsedRows(parents: number[], action: 'collapse' | 'expand', shouldRunHooks?: boolean): boolean;
+    /**
+     * Same as `toggleCollapsedRows`, but it also reports whether a `before*` hook blocked the action.
+     *
+     * A caller that performs two passes needs that apart from `performed`: `performed` is `false` both
+     * when a hook blocked the change and when there was simply nothing to do, and those two cases call
+     * for opposite decisions.
+     *
+     * @param {number[]} parents Physical row indexes of the parents to act on.
+     * @param {string} action Either `'collapse'` or `'expand'`.
+     * @param {boolean} [shouldRunHooks=true] `false` skips both hooks.
+     * @returns {{performed: boolean, vetoed: boolean}} `performed` says the collapsed state changed,
+     * `vetoed` says a `before*` hook returned `false`.
+     * @fires Hooks#beforeRowCollapse
+     * @fires Hooks#afterRowCollapse
+     * @fires Hooks#beforeRowExpand
+     * @fires Hooks#afterRowExpand
+     */
+    applyCollapsedRowsChange(parents: number[], action: 'collapse' | 'expand', shouldRunHooks?: boolean): {
+        performed: boolean;
+        vetoed: boolean;
+    };
     /**
      * Collapse all collapsable rows.
      */
     collapseAll(): void;
     /**
      * Expand all collapsable rows.
+     *
+     * Acts on the top-level parents, which leaves a parent that was collapsed inside another one
+     * collapsed. Use `NestedRows#expandAll` to expand every level.
      */
     expandAll(): void;
+    /**
+     * Collapsed parents ordered from the shallowest to the deepest, so an ancestor is always handled
+     * before its own descendants.
+     *
+     * @returns {number[]} Physical row indexes.
+     */
+    getCollapsedParentsShallowestFirst(): number[];
     /**
      * Trim rows.
      *