tree-element 0.3.2 → 0.4.1

package/src/index.ts

@@ -2,7 +2,7 @@ import type { ClassNames } from "./classNames";
 import type { TreeEventName, TreeEvents } from "./events";
 import type { PositionInfo } from "./mouseUtils";
 import type { NodeData, NodeId, Position } from "./node";
-import type { TreeElementOptions } from "./options";
+import type { ChangeableOption, TreeElementOptions } from "./options";
 import type { SavedState } from "./saveStateHandler";
 import type { SelectNodeOptions } from "./selectNodeHandler";
 
@@ -15,6 +15,7 @@ import MouseHandler from "./mouseHandler";
 import { Node } from "./node";
 import NodeElement from "./nodeElement";
 import FolderElement from "./nodeElement/folderElement";
+import { changeableOptions } from "./options";
 import { getOffsetTop } from "./positionUtils";
 import RequestUrl from "./requestUrl";
 import SaveStateHandler from "./saveStateHandler";
@@ -47,6 +48,8 @@ interface TreeElementParams extends Partial<TreeElementOptions> {
 }
 
 export default class TreeElement {
+  // With multiSelect: the node that is the tab stop, see updateTabStop
+  private activeNode: Node | null;
   private classNames: ClassNames;
   private dataLoader: DataLoader;
   private dndHandler: DragAndDropHandler;
@@ -82,6 +85,7 @@ export default class TreeElement {
     this.tree = new Node({}, true);
     this.nodeMap = new WeakMap();
     this.fallbackTabStop = null;
+    this.activeNode = null;
 
     const {
       ariaLabel,
@@ -92,6 +96,7 @@ export default class TreeElement {
       dataFilter,
       dragAndDrop,
       keyboardSupport,
+      multiSelect,
       onCanMove,
       onCanMoveTo,
       onCreateLi,
@@ -105,7 +110,6 @@ export default class TreeElement {
       rtl,
       saveState: saveStateOption,
       showEmptyFolder,
-      slide,
       tabIndex,
     } = this.options;
 
@@ -153,6 +157,19 @@ export default class TreeElement {
     const selectNode =
       selectNodeHandler.selectSingleNode.bind(selectNodeHandler);
 
+    const toggleNodeInSelection =
+      selectNodeHandler.toggleNodeInSelection.bind(selectNodeHandler);
+
+    // With multiSelect, a click adds a node to the selection or removes it
+    const onClickTitle = (node: Node) => {
+      if (this.options.multiSelect) {
+        toggleNodeInSelection(node, false);
+        this.focusNode(node);
+      } else {
+        selectNode(node);
+      }
+    };
+
     const getMouseDelay = () => this.options.startDndDelay ?? 0;
 
     const dataLoader = new DataLoader({
@@ -198,19 +215,22 @@ export default class TreeElement {
       openFolderDelay,
       openNode,
       refreshElements,
-      slide,
       treeElement,
       triggerEvent,
     });
 
     const keyHandler = new KeyHandler({
       closeNode,
+      focusNode: this.focusNode.bind(this),
+      getActiveNode: this.getActiveNode.bind(this),
       getFocusedNode,
       getSelectedNode,
       getTree,
       keyboardSupport,
+      multiSelect,
       openNode,
       selectNode,
+      toggleNodeInSelection,
       triggerEvent,
     });
 
@@ -225,6 +245,7 @@ export default class TreeElement {
       getTree,
       htmlElement: treeElement,
       isNodeSelected,
+      multiSelect,
       onCreateLi,
       openedIcon,
       rtl,
@@ -245,7 +266,7 @@ export default class TreeElement {
       getMouseDelay,
       getNode,
       onClickButton: this.toggle.bind(this),
-      onClickTitle: selectNode,
+      onClickTitle,
       onMouseCapture,
       onMouseDrag,
       onMouseStart,
@@ -263,6 +284,10 @@ export default class TreeElement {
     this.scrollHandler = scrollHandler;
     this.selectNodeHandler = selectNodeHandler;
 
+    if (multiSelect) {
+      treeElement.addEventListener("focusin", this.handleFocusIn);
+    }
+
     this.initData();
   }
 
@@ -299,8 +324,9 @@ export default 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
@@ -388,6 +414,7 @@ export default class TreeElement {
     this.dataLoader.deinit();
     this.keyHandler.deinit();
     this.mouseHandler.deinit();
+    this.htmlElement.removeEventListener("focusin", this.handleFocusIn);
 
     this.tree = new Node({}, true);
   }
@@ -485,7 +512,7 @@ export default 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
@@ -504,7 +531,7 @@ export default 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
@@ -584,7 +611,8 @@ export default 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
    */
@@ -609,7 +637,8 @@ export default 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
    */
@@ -618,7 +647,7 @@ export default 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.
    *
@@ -638,7 +667,7 @@ export default class TreeElement {
       openedNode: Node,
       slideOption: boolean,
     ): Promise<void> => {
-      if (!node.children.length) {
+      if (!openedNode.children.length) {
         return;
       }
 
@@ -754,8 +783,8 @@ export default class TreeElement {
    */
   public selectNode(node: Node | null, options?: SelectNodeOptions): void {
     if (!node) {
-      // Called with empty node -> deselect current node
-      this.deselectCurrentNode();
+      // Called with empty node -> deselect all nodes
+      this.deselectAllNodes();
       this.saveStateHandler.saveState();
       return;
     }
@@ -768,13 +797,47 @@ export default 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
    */
-  public setOption(option: string, value: unknown) {
+  public setOption(option: ChangeableOption, value: unknown) {
+    if (!(changeableOptions as readonly string[]).includes(option)) {
+      throw new Error(
+        `The option ${option} can only be set in the constructor`,
+      );
+    }
+
     (this.options as unknown as Record<string, unknown>)[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 as null | number) ?? undefined;
+        this.renderer.setTabIndex(this.options.tabIndex);
+        this.fallbackTabStop = null;
+        this.updateTabStop();
+
+        break;
+      }
+      // No default
+    }
   }
 
   /**
@@ -808,8 +871,8 @@ export default 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
    */
@@ -822,7 +885,7 @@ export default 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
@@ -891,11 +954,9 @@ export default class TreeElement {
 
   private createFolderElement(node: Node) {
     const classNames = this.classNames;
-    const closedIconElement = this.renderer.closedIconElement;
     const getScrollLeft = this.scrollHandler.getScrollLeft.bind(
       this.scrollHandler,
     );
-    const openedIconElement = this.renderer.openedIconElement;
     const tabIndex = this.options.tabIndex;
     const treeElement = this.htmlElement;
     const triggerEvent = this.triggerEvent.bind(this);
@@ -911,10 +972,10 @@ export default class TreeElement {
 
     return new FolderElement({
       classNames,
-      closedIconElement,
       getScrollLeft,
+      icons: this.renderer.icons,
+      multiSelect: this.options.multiSelect,
       node,
-      openedIconElement,
       renderChildren,
       tabIndex,
       treeElement,
@@ -933,6 +994,7 @@ export default class TreeElement {
     return new NodeElement({
       classNames,
       getScrollLeft,
+      multiSelect: this.options.multiSelect,
       node,
       tabIndex,
       treeElement,
@@ -968,9 +1030,8 @@ export default class TreeElement {
     return requestUrl;
   }
 
-  private deselectCurrentNode(): void {
-    const node = this.getSelectedNode();
-    if (node) {
+  private deselectAllNodes(): void {
+    for (const node of this.getSelectedNodes()) {
       this.removeFromSelection(node);
     }
   }
@@ -984,6 +1045,23 @@ export default class TreeElement {
     }
   }
 
+  // The treeitem of the first node, or null when the tree is empty
+  // Move the focus to a node, without selecting it
+  private focusNode(node: Node): void {
+    this.activeNode = node;
+    this.updateTabStop();
+    node.element?.focus();
+  }
+
+  // With multiSelect: the active node, if it is still rendered in the tree
+  private getActiveNode(): Node | null {
+    const element = this.activeNode?.element;
+
+    return element && this.htmlElement.contains(element)
+      ? this.activeNode
+      : null;
+  }
+
   // Get the maximum level for auto open
   private getAutoOpenMaxLevel(): number {
     if (this.options.autoOpen === true) {
@@ -1000,29 +1078,19 @@ export default class TreeElement {
     return 0;
   }
 
-  // The title span of the first node, or null when the tree is empty
-  private getFirstTitleSpan(): HTMLElement | null {
-    const firstElement = this.tree.children[0]?.element;
-
-    return firstElement
-      ? firstElement.querySelector<HTMLElement>(
-          `:scope > .${this.classNames.element} > span.${this.classNames.title}`,
-        )
-      : null;
+  private getFirstTreeItem(): HTMLElement | null {
+    return this.tree.children[0]?.element ?? null;
   }
 
   // The node of the HTML element that has the focus, if it is in this tree
   private getFocusedNode(): Node | null {
     const activeElement = document.activeElement;
 
-    /* istanbul ignore if */
-    if (!activeElement) {
-      return null;
-    }
-
-    // The keyboard must still work for input elements.
-    const 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;
     }
 
@@ -1045,6 +1113,18 @@ export default class TreeElement {
     return this.saveStateHandler.getNodeIdToBeSelected();
   }
 
+  // With multiSelect, the focused node becomes the tab stop
+  private handleFocusIn = (): void => {
+    const node = this.getFocusedNode();
+
+    if (!node || node === this.activeNode) {
+      return;
+    }
+
+    this.activeNode = node;
+    this.updateTabStop();
+  };
+
   private hasRenderedSelectedNode(): boolean {
     return this.getSelectedNodes().some((node) => Boolean(node.element));
   }
@@ -1073,6 +1153,9 @@ export default class TreeElement {
       this.triggerEvent("tree.init");
     };
 
+    // Before the tree is replaced: then the focused node is no longer in it
+    const focusedNode = this.getFocusedNode();
+
     this.tree = new this.options.nodeClass(null, true, this.options.nodeClass);
 
     this.selectNodeHandler.clear();
@@ -1083,6 +1166,10 @@ export default class TreeElement {
 
     this.refreshElements(null);
 
+    if (focusedNode) {
+      this.restoreFocus(focusedNode);
+    }
+
     if (mustLoadOnDemand) {
       // Load data on demand and then init the tree
       void this.setInitialStateOnDemand().then(doInit);
@@ -1091,19 +1178,6 @@ export default class TreeElement {
     }
   }
 
-  // Does an HTML element of the tree have the focus?
-  private isFocusOnTree(): boolean {
-    return this.getFocusedNode() !== null;
-  }
-
-  private isSelectedNodeInSubtree(subtree: Node): boolean {
-    const selectedNode = this.getSelectedNode();
-
-    return selectedNode
-      ? subtree === selectedNode || subtree.isParentOf(selectedNode)
-      : false;
-  }
-
   private async loadFolderOnDemand(node: Node, slide: boolean): Promise<void> {
     node.is_loading = true;
 
@@ -1147,7 +1221,6 @@ export default class TreeElement {
 
   private mouseStart(positionInfo: PositionInfo): boolean {
     /* istanbul ignore if */
-    // eslint-disable-next-line unicorn/prefer-ternary
     if (!this.options.dragAndDrop) {
       return false;
     }
@@ -1155,14 +1228,14 @@ export default class TreeElement {
     return this.dndHandler.mouseStart(positionInfo);
   }
 
-  private mouseStop(positionInfo: PositionInfo): boolean {
+  private mouseStop(positionInfo: PositionInfo): void {
     /* istanbul ignore if */
     if (!this.options.dragAndDrop) {
-      return false;
+      return;
     }
 
     this.scrollHandler.stopScrolling();
-    return this.dndHandler.mouseStop(positionInfo);
+    this.dndHandler.mouseStop(positionInfo);
   }
 
   private openParents(node: Node) {
@@ -1178,15 +1251,13 @@ export default class TreeElement {
     from_node: redraw this subtree
   */
   private refreshElements(fromNode: Node | null): void {
-    const mustSetFocus = this.isFocusOnTree();
-    const mustSelect = fromNode
-      ? this.isSelectedNodeInSubtree(fromNode)
-      : false;
+    const 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();
@@ -1194,18 +1265,26 @@ export default class TreeElement {
     this.triggerEvent("tree.refresh");
   }
 
-  private saveState(): void {
-    this.saveStateHandler.saveState();
-  }
-
-  private selectCurrentNode(mustSetFocus: boolean): void {
-    const 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.
+  private restoreFocus(focusedNode: Node): void {
+    if (this.htmlElement.contains(document.activeElement)) {
       return;
     }
 
-    const nodeElement = this.getNodeElementForNode(node);
-    nodeElement.select(mustSetFocus);
+    const node =
+      (focusedNode.id == null ? null : this.getNodeById(focusedNode.id)) ??
+      focusedNode;
+    const element = node.element;
+
+    if (element && this.htmlElement.contains(element)) {
+      element.focus();
+    }
+  }
+
+  private saveState(): void {
+    this.saveStateHandler.saveState();
   }
 
   // Set initial state, either by restoring the state or auto-opening nodes
@@ -1268,6 +1347,28 @@ export default 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.
+   */
+  private setMultiSelect(multiSelect: boolean): void {
+    const 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.
   private setNodeElement(element: HTMLElement, node: Node) {
     this.nodeMap.set(element, node);
@@ -1283,19 +1384,27 @@ export default 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.
    */
   private updateTabStop(): void {
     const tabIndex = this.options.tabIndex;
+    const multiSelect = this.options.multiSelect;
     const previousTabStop = this.fallbackTabStop;
-    const tabStop =
-      tabIndex == null || this.hasRenderedSelectedNode()
-        ? null
-        : this.getFirstTitleSpan();
+    let tabStop: HTMLElement | null;
+
+    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 &&
-      previousTabStop.getAttribute("aria-selected") !== "true"
+      (multiSelect || previousTabStop.getAttribute("aria-selected") !== "true")
     ) {
       previousTabStop.setAttribute("tabindex", "-1");
     }
@@ -1315,6 +1424,6 @@ export {
   type TreeEvents,
 } from "./events";
 export { type Node, type NodeData, type NodeId, type Position } from "./node";
-export { type TreeElementOptions } from "./options";
+export { type ChangeableOption, type TreeElementOptions } from "./options";
 export { type SavedState } from "./saveStateHandler";
 export { type SelectNodeOptions } from "./selectNodeHandler";