tree-element 0.3.2 → 0.4.1

package/lib/index.js

@@ -1,5 +1,5 @@
 /*
-Tree-element 0.3.2
+Tree-element 0.4.1
 
 Copyright 2026 Marco Braak
 
@@ -26,6 +26,7 @@ import MouseHandler from './mouseHandler.js';
 import { Node } from './node.js';
 import NodeElement from './nodeElement/index.js';
 import FolderElement from './nodeElement/folderElement.js';
+import { changeableOptions } from './options.js';
 import { getOffsetTop } from './positionUtils.js';
 import RequestUrl from './requestUrl.js';
 import SaveStateHandler from './saveStateHandler.js';
@@ -41,6 +42,8 @@ import version from './version.js';
 // as its global, instead of an object of named exports.
 
 class TreeElement {
+  // With multiSelect: the node that is the tab stop, see updateTabStop
+  _activeNode;
   _classNames;
   _dataLoader;
   _dndHandler;
@@ -74,6 +77,7 @@ class TreeElement {
     this._tree = new Node({}, true);
     this._nodeMap = new WeakMap();
     this._fallbackTabStop = null;
+    this._activeNode = null;
     let {
       ariaLabel,
       ariaLabelledBy,
@@ -83,6 +87,7 @@ class TreeElement {
       dataFilter,
       dragAndDrop,
       keyboardSupport,
+      multiSelect,
       onCanMove,
       onCanMoveTo,
       onCreateLi,
@@ -96,7 +101,6 @@ class TreeElement {
       rtl,
       saveState: saveStateOption,
       showEmptyFolder,
-      slide,
       tabIndex
     } = this._options;
     let classNames = this._classNames;
@@ -134,6 +138,17 @@ class TreeElement {
     let isNodeSelected = selectNodeHandler._isNodeSelected.bind(selectNodeHandler);
     let removeFromSelection = selectNodeHandler._removeFromSelection.bind(selectNodeHandler);
     let selectNode = selectNodeHandler._selectSingleNode.bind(selectNodeHandler);
+    let toggleNodeInSelection = selectNodeHandler._toggleNodeInSelection.bind(selectNodeHandler);
+
+    // With multiSelect, a click adds a node to the selection or removes it
+    let onClickTitle = node => {
+      if (this._options.multiSelect) {
+        toggleNodeInSelection(node, false);
+        this._focusNode(node);
+      } else {
+        selectNode(node);
+      }
+    };
     let getMouseDelay = () => this._options.startDndDelay ?? 0;
     let dataLoader = new DataLoader({
       _classNames: classNames,
@@ -174,18 +189,21 @@ class TreeElement {
       _openFolderDelay: openFolderDelay,
       _openNode: openNode,
       _refreshElements: refreshElements,
-      _slide: slide,
       _treeElement: treeElement,
       _triggerEvent: triggerEvent
     });
     let keyHandler = new KeyHandler({
       _closeNode: closeNode,
+      _focusNode: this._focusNode.bind(this),
+      _getActiveNode: this._getActiveNode.bind(this),
       _getFocusedNode: getFocusedNode,
       _getSelectedNode: getSelectedNode,
       _getTree: getTree,
       _keyboardSupport: keyboardSupport,
+      _multiSelect: multiSelect,
       _openNode: openNode,
       _selectNode: selectNode,
+      _toggleNodeInSelection: toggleNodeInSelection,
       _triggerEvent: triggerEvent
     });
     let renderer = new ElementsRenderer({
@@ -199,6 +217,7 @@ class TreeElement {
       _getTree: getTree,
       _htmlElement: treeElement,
       _isNodeSelected: isNodeSelected,
+      _multiSelect: multiSelect,
       _onCreateLi: onCreateLi,
       _openedIcon: openedIcon,
       _rtl: rtl,
@@ -217,7 +236,7 @@ class TreeElement {
       _getMouseDelay: getMouseDelay,
       _getNode: getNode,
       _onClickButton: this.toggle.bind(this),
-      _onClickTitle: selectNode,
+      _onClickTitle: onClickTitle,
       _onMouseCapture: onMouseCapture,
       _onMouseDrag: onMouseDrag,
       _onMouseStart: onMouseStart,
@@ -233,6 +252,9 @@ class TreeElement {
     this._saveStateHandler = saveStateHandler;
     this._scrollHandler = scrollHandler;
     this._selectNodeHandler = selectNodeHandler;
+    if (multiSelect) {
+      treeElement.addEventListener("focusin", this._handleFocusIn);
+    }
     this._initData();
   }
 
@@ -265,8 +287,9 @@ class TreeElement {
   }
 
   /**
-   * Inserts a new node between a node and its parent, taking the node as its
-   * child.
+   * Inserts a new node between a node and its parent. The siblings of the node
+   * move along: the new node takes all children of the parent, and becomes its
+   * only child.
    *
    * @returns The new node, or `null` when the node has no parent.
    * @group Changing the tree
@@ -342,6 +365,7 @@ class TreeElement {
     this._dataLoader._deinit();
     this._keyHandler._deinit();
     this._mouseHandler._deinit();
+    this._htmlElement.removeEventListener("focusin", this._handleFocusIn);
     this._tree = new Node({}, true);
   }
 
@@ -435,7 +459,7 @@ class TreeElement {
   }
 
   /**
-   * Returns the current state — `open_nodes` and `selected_node` — whether or
+   * Returns the current state—`open_nodes` and `selected_node`—whether or
    * not `saveState` is enabled.
    *
    * @group State
@@ -454,7 +478,7 @@ class TreeElement {
   }
 
   /**
-   * Returns the root node. It is not rendered; its `children` are the
+   * Returns the root node. It is not rendered, and its `children` are the
    * top-level nodes. Also available as the `tree` property.
    *
    * @group Finding nodes
@@ -529,7 +553,8 @@ class TreeElement {
   }
 
   /**
-   * Selects the next visible node, like the down arrow key.
+   * Selects the next visible node, like the down arrow key. With
+   * `multiSelect` it moves the focus instead.
    *
    * @group Selection
    */
@@ -554,7 +579,8 @@ class TreeElement {
   }
 
   /**
-   * Selects the previous visible node, like the up arrow key.
+   * Selects the previous visible node, like the up arrow key. With
+   * `multiSelect` it moves the focus instead.
    *
    * @group Selection
    */
@@ -563,7 +589,7 @@ class TreeElement {
   }
 
   /**
-   * Opens a folder, and the folders above it. A node marked `load_on_demand`
+   * Opens a folder, and the folders that contain it. A node marked `load_on_demand`
    * is fetched first, so await the promise when you need to know it is really
    * open.
    *
@@ -579,7 +605,7 @@ class TreeElement {
   async openNode(node, slide) {
     let mustSlide = slide ?? this._options.slide;
     let doOpenNode = async (openedNode, slideOption) => {
-      if (!node.children.length) {
+      if (!openedNode.children.length) {
         return;
       }
       let folderElement = this._createFolderElement(openedNode);
@@ -684,8 +710,8 @@ class TreeElement {
    */
   selectNode(node, options) {
     if (!node) {
-      // Called with empty node -> deselect current node
-      this._deselectCurrentNode();
+      // Called with empty node -> deselect all nodes
+      this._deselectAllNodes();
       this._saveStateHandler._saveState();
       return;
     }
@@ -698,13 +724,43 @@ class TreeElement {
   }
 
   /**
-   * Changes an option after construction. See
-   * [Options](/reference/options#changing-an-option-later) for the caveats.
+   * Changes an option after construction. Only some options can be changed:
+   * the others throw an error. See
+   * [Options](/reference/options#changing-an-option-later).
    *
    * @group Other
    */
   setOption(option, value) {
+    if (!changeableOptions.includes(option)) {
+      throw new Error(`The option ${option} can only be set in the constructor`);
+    }
     this._options[option] = value;
+    switch (option) {
+      case "dragAndDrop":
+        {
+          this._renderer._setDragAndDrop(Boolean(value));
+          break;
+        }
+      case "keyboardSupport":
+        {
+          this._keyHandler._setKeyboardSupport(Boolean(value));
+          break;
+        }
+      case "multiSelect":
+        {
+          this._setMultiSelect(Boolean(value));
+          break;
+        }
+      case "tabIndex":
+        {
+          this._options.tabIndex = value ?? undefined;
+          this._renderer._setTabIndex(this._options.tabIndex);
+          this._fallbackTabStop = null;
+          this._updateTabStop();
+          break;
+        }
+      // No default
+    }
   }
 
   /**
@@ -737,8 +793,8 @@ class TreeElement {
   }
 
   /**
-   * Returns the tree as a json string, including changes made through the
-   * api.
+   * Returns the tree as a JSON string, including changes made through the
+   * API.
    *
    * @group Other
    */
@@ -751,7 +807,7 @@ class TreeElement {
    * name.
    *
    * Changing the `id` re-indexes the node. `children` and `parent` are
-   * ignored — use `loadData` or `moveNode` for those.
+   * ignored—use `loadData` or `moveNode` for those.
    *
    * @example
    * ```js
@@ -802,9 +858,7 @@ class TreeElement {
   }
   _createFolderElement(node) {
     let classNames = this._classNames;
-    let closedIconElement = this._renderer._closedIconElement;
     let getScrollLeft = this._scrollHandler._getScrollLeft.bind(this._scrollHandler);
-    let openedIconElement = this._renderer._openedIconElement;
     let tabIndex = this._options.tabIndex;
     let treeElement = this._htmlElement;
     let triggerEvent = this._triggerEvent.bind(this);
@@ -819,10 +873,10 @@ class TreeElement {
     };
     return new FolderElement({
       _classNames: classNames,
-      _closedIconElement: closedIconElement,
       _getScrollLeft: getScrollLeft,
+      _icons: this._renderer._icons,
+      _multiSelect: this._options.multiSelect,
       _node: node,
-      _openedIconElement: openedIconElement,
       _renderChildren: renderChildren,
       _tabIndex: tabIndex,
       _treeElement: treeElement,
@@ -837,6 +891,7 @@ class TreeElement {
     return new NodeElement({
       _classNames: classNames,
       _getScrollLeft: getScrollLeft,
+      _multiSelect: this._options.multiSelect,
       _node: node,
       _tabIndex: tabIndex,
       _treeElement: treeElement
@@ -866,9 +921,8 @@ class TreeElement {
     }
     return requestUrl;
   }
-  _deselectCurrentNode() {
-    let node = this.getSelectedNode();
-    if (node) {
+  _deselectAllNodes() {
+    for (let node of this.getSelectedNodes()) {
       this.removeFromSelection(node);
     }
   }
@@ -881,6 +935,20 @@ class TreeElement {
     }
   }
 
+  // The treeitem of the first node, or null when the tree is empty
+  // Move the focus to a node, without selecting it
+  _focusNode(node) {
+    this._activeNode = node;
+    this._updateTabStop();
+    node.element?.focus();
+  }
+
+  // With multiSelect: the active node, if it is still rendered in the tree
+  _getActiveNode() {
+    let element = this._activeNode?.element;
+    return element && this._htmlElement.contains(element) ? this._activeNode : null;
+  }
+
   // Get the maximum level for auto open
   _getAutoOpenMaxLevel() {
     if (this._options.autoOpen === true) {
@@ -896,25 +964,16 @@ class TreeElement {
     /* istanbul ignore next @preserve */
     return 0;
   }
-
-  // The title span of the first node, or null when the tree is empty
-  _getFirstTitleSpan() {
-    let firstElement = this._tree.children[0]?.element;
-    return firstElement ? firstElement.querySelector(`:scope > .${this._classNames.element} > span.${this._classNames.title}`) : null;
+  _getFirstTreeItem() {
+    return this._tree.children[0]?.element ?? null;
   }
 
   // The node of the HTML element that has the focus, if it is in this tree
   _getFocusedNode() {
     let activeElement = document.activeElement;
 
-    /* istanbul ignore if */
-    if (!activeElement) {
-      return null;
-    }
-
-    // The keyboard must still work for input elements.
-    let tagName = activeElement.tagName;
-    if (tagName !== "A" && tagName !== "SPAN") {
+    // An active element must exist and the keyboard must still work for input elements.
+    if (!activeElement || !["A", "LI", "SPAN"].includes(activeElement.tagName)) {
       return null;
     }
     let node = this.getNode(activeElement);
@@ -930,6 +989,16 @@ class TreeElement {
   _getNodeIdToBeSelected() {
     return this._saveStateHandler._getNodeIdToBeSelected();
   }
+
+  // With multiSelect, the focused node becomes the tab stop
+  _handleFocusIn = () => {
+    let node = this._getFocusedNode();
+    if (!node || node === this._activeNode) {
+      return;
+    }
+    this._activeNode = node;
+    this._updateTabStop();
+  };
   _hasRenderedSelectedNode() {
     return this.getSelectedNodes().some(node => Boolean(node.element));
   }
@@ -953,11 +1022,17 @@ class TreeElement {
       this._isInitialized = true;
       this._triggerEvent("tree.init");
     };
+
+    // Before the tree is replaced: then the focused node is no longer in it
+    let focusedNode = this._getFocusedNode();
     this._tree = new this._options.nodeClass(null, true, this._options.nodeClass);
     this._selectNodeHandler._clear();
     this._tree.loadFromData(data);
     let mustLoadOnDemand = this._setInitialState();
     this._refreshElements(null);
+    if (focusedNode) {
+      this._restoreFocus(focusedNode);
+    }
     if (mustLoadOnDemand) {
       // Load data on demand and then init the tree
       void this._setInitialStateOnDemand().then(doInit);
@@ -965,15 +1040,6 @@ class TreeElement {
       doInit();
     }
   }
-
-  // Does an HTML element of the tree have the focus?
-  _isFocusOnTree() {
-    return this._getFocusedNode() !== null;
-  }
-  _isSelectedNodeInSubtree(subtree) {
-    let selectedNode = this.getSelectedNode();
-    return selectedNode ? subtree === selectedNode || subtree.isParentOf(selectedNode) : false;
-  }
   async _loadFolderOnDemand(node, slide) {
     node.is_loading = true;
     await this.loadDataFromUrl(undefined, node);
@@ -1006,7 +1072,6 @@ class TreeElement {
   }
   _mouseStart(positionInfo) {
     /* istanbul ignore if */
-    // eslint-disable-next-line unicorn/prefer-ternary
     if (!this._options.dragAndDrop) {
       return false;
     }
@@ -1015,10 +1080,10 @@ class TreeElement {
   _mouseStop(positionInfo) {
     /* istanbul ignore if */
     if (!this._options.dragAndDrop) {
-      return false;
+      return;
     }
     this._scrollHandler._stopScrolling();
-    return this._dndHandler._mouseStop(positionInfo);
+    this._dndHandler._mouseStop(positionInfo);
   }
   _openParents(node) {
     let parent = node.parent;
@@ -1032,25 +1097,32 @@ class TreeElement {
     from_node: redraw this subtree
   */
   _refreshElements(fromNode) {
-    let mustSetFocus = this._isFocusOnTree();
-    let mustSelect = fromNode ? this._isSelectedNodeInSubtree(fromNode) : false;
+    let focusedNode = this._getFocusedNode();
+
+    // The renderer marks the selected nodes, so only the focus needs restoring
     this._renderer._render(fromNode);
-    if (mustSelect) {
-      this._selectCurrentNode(mustSetFocus);
+    if (focusedNode) {
+      this._restoreFocus(focusedNode);
     }
     this._updateTabStop();
     this._triggerEvent("tree.refresh");
   }
-  _saveState() {
-    this._saveStateHandler._saveState();
-  }
-  _selectCurrentNode(mustSetFocus) {
-    let node = this.getSelectedNode();
-    if (!node) {
+
+  // Rendering replaces the elements of the nodes, so a focused element can be
+  // gone. Then move the focus to the new element of the same node. After
+  // loadData the nodes are new objects, so look the node up by its id.
+  _restoreFocus(focusedNode) {
+    if (this._htmlElement.contains(document.activeElement)) {
       return;
     }
-    let nodeElement = this._getNodeElementForNode(node);
-    nodeElement._select(mustSetFocus);
+    let node = (focusedNode.id == null ? null : this.getNodeById(focusedNode.id)) ?? focusedNode;
+    let element = node.element;
+    if (element && this._htmlElement.contains(element)) {
+      element.focus();
+    }
+  }
+  _saveState() {
+    this._saveStateHandler._saveState();
   }
 
   // Set initial state, either by restoring the state or auto-opening nodes
@@ -1105,6 +1177,25 @@ class TreeElement {
     }
   }
 
+  /* Change multiSelect after construction. The attributes of the nodes
+   * depend on it, so the tree is rendered again. The selection is kept: a
+   * tree without multiSelect can also have several selected nodes, see
+   * addToSelection.
+   */
+  _setMultiSelect(multiSelect) {
+    let focusedNode = this._getFocusedNode();
+    this._keyHandler._setMultiSelect(multiSelect);
+    this._renderer._setMultiSelect(multiSelect);
+    if (multiSelect) {
+      this._htmlElement.addEventListener("focusin", this._handleFocusIn);
+    } else {
+      this._htmlElement.removeEventListener("focusin", this._handleFocusIn);
+    }
+    this._activeNode = multiSelect ? focusedNode : null;
+    this._fallbackTabStop = null;
+    this._refreshElements(null);
+  }
+
   // Set this HTML element to this node in the node map.
   _setNodeElement(element, node) {
     this._nodeMap.set(element, node);
@@ -1116,12 +1207,22 @@ class TreeElement {
   /* Keyboard users reach the tree through the tab stop. The selected node is
    * the tab stop, see NodeElement.select. Without a selected node, the first
    * node is the tab stop, so the tree can always be reached.
+   * With multiSelect the tab stop is the active node: the node that was
+   * focused last. Without one, it is the first node.
    */
   _updateTabStop() {
     let tabIndex = this._options.tabIndex;
+    let multiSelect = this._options.multiSelect;
     let previousTabStop = this._fallbackTabStop;
-    let tabStop = tabIndex == null || this._hasRenderedSelectedNode() ? null : this._getFirstTitleSpan();
-    if (previousTabStop && previousTabStop !== tabStop && previousTabStop.getAttribute("aria-selected") !== "true") {
+    let tabStop;
+    if (tabIndex == null) {
+      tabStop = null;
+    } else if (multiSelect) {
+      tabStop = this._getActiveNode()?.element ?? this._getFirstTreeItem();
+    } else {
+      tabStop = this._hasRenderedSelectedNode() ? null : this._getFirstTreeItem();
+    }
+    if (previousTabStop && previousTabStop !== tabStop && (multiSelect || previousTabStop.getAttribute("aria-selected") !== "true")) {
       previousTabStop.setAttribute("tabindex", "-1");
     }
     if (tabStop && tabIndex != null) {