tree-element 0.3.2 → 0.4.0

package/src/index.ts

@@ -47,6 +47,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 +84,7 @@ export default class TreeElement {
     this.tree = new Node({}, true);
     this.nodeMap = new WeakMap();
     this.fallbackTabStop = null;
+    this.activeNode = null;
 
     const {
       ariaLabel,
@@ -92,6 +95,7 @@ export default class TreeElement {
       dataFilter,
       dragAndDrop,
       keyboardSupport,
+      multiSelect,
       onCanMove,
       onCanMoveTo,
       onCreateLi,
@@ -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({
@@ -205,12 +222,16 @@ export default class TreeElement {
 
     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 +246,7 @@ export default class TreeElement {
       getTree,
       htmlElement: treeElement,
       isNodeSelected,
+      multiSelect,
       onCreateLi,
       openedIcon,
       rtl,
@@ -245,7 +267,7 @@ export default class TreeElement {
       getMouseDelay,
       getNode,
       onClickButton: this.toggle.bind(this),
-      onClickTitle: selectNode,
+      onClickTitle,
       onMouseCapture,
       onMouseDrag,
       onMouseStart,
@@ -263,6 +285,10 @@ export default class TreeElement {
     this.scrollHandler = scrollHandler;
     this.selectNodeHandler = selectNodeHandler;
 
+    if (multiSelect) {
+      treeElement.addEventListener("focusin", this.handleFocusIn);
+    }
+
     this.initData();
   }
 
@@ -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);
   }
@@ -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
    */
@@ -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;
     }
@@ -913,6 +942,7 @@ export default class TreeElement {
       classNames,
       closedIconElement,
       getScrollLeft,
+      multiSelect: this.options.multiSelect,
       node,
       openedIconElement,
       renderChildren,
@@ -933,6 +963,7 @@ export default class TreeElement {
     return new NodeElement({
       classNames,
       getScrollLeft,
+      multiSelect: this.options.multiSelect,
       node,
       tabIndex,
       treeElement,
@@ -968,9 +999,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 +1014,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,15 +1047,8 @@ 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
@@ -1022,7 +1062,7 @@ export default class TreeElement {
 
     // The keyboard must still work for input elements.
     const tagName = activeElement.tagName;
-    if (tagName !== "A" && tagName !== "SPAN") {
+    if (tagName !== "A" && tagName !== "LI" && tagName !== "SPAN") {
       return null;
     }
 
@@ -1045,6 +1085,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));
   }
@@ -1147,7 +1199,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;
     }
@@ -1283,19 +1334,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");
     }

package/src/keyHandler.ts

@@ -1,53 +1,77 @@
 import type {
   CloseNode,
+  FocusNode,
+  GetActiveNode,
   GetFocusedNode,
   GetSelectedNode,
   GetTree,
   OpenNode,
   SelectNode,
+  ToggleNodeInSelection,
   TriggerEvent,
 } from "./methodTypes";
 import type { Node } from "./node";
 
 interface KeyHandlerParams {
   closeNode: CloseNode;
+  focusNode: FocusNode;
+  getActiveNode: GetActiveNode;
   getFocusedNode: GetFocusedNode;
   getSelectedNode: GetSelectedNode;
   getTree: GetTree;
   keyboardSupport: boolean;
+  multiSelect: boolean;
   openNode: OpenNode;
   selectNode: SelectNode;
+  toggleNodeInSelection: ToggleNodeInSelection;
   triggerEvent: TriggerEvent;
 }
 
+/* The keys move from the selected node and select the node they move to.
+ * With multiSelect they move from the focused node and only move the focus;
+ * Space adds the focused node to the selection or removes it.
+ */
+
 export default class KeyHandler {
   private closeNode: CloseNode;
+  private focusNode: FocusNode;
+  private getActiveNode: GetActiveNode;
   private getFocusedNode: GetFocusedNode;
   private getSelectedNode: GetSelectedNode;
   private getTree: GetTree;
 
   private keyboardSupport: boolean;
+  private multiSelect: boolean;
   private openNode: OpenNode;
   private originalSelectNode: SelectNode;
+  private toggleNodeInSelection: ToggleNodeInSelection;
   private triggerEvent: TriggerEvent;
 
   constructor({
     closeNode,
+    focusNode,
+    getActiveNode,
     getFocusedNode,
     getSelectedNode,
     getTree,
     keyboardSupport,
+    multiSelect,
     openNode,
     selectNode,
+    toggleNodeInSelection,
     triggerEvent,
   }: KeyHandlerParams) {
     this.closeNode = closeNode;
+    this.focusNode = focusNode;
+    this.getActiveNode = getActiveNode;
     this.getFocusedNode = getFocusedNode;
     this.getSelectedNode = getSelectedNode;
     this.getTree = getTree;
     this.keyboardSupport = keyboardSupport;
+    this.multiSelect = multiSelect;
     this.openNode = openNode;
     this.originalSelectNode = selectNode;
+    this.toggleNodeInSelection = toggleNodeInSelection;
     this.triggerEvent = triggerEvent;
 
     if (keyboardSupport) {
@@ -62,11 +86,11 @@ export default class KeyHandler {
   }
 
   public moveDown(): boolean {
-    return this.selectNode(this.getSelectedNode()?.getNextVisibleNode());
+    return this.goToNode(this.getCurrentNode()?.getNextVisibleNode());
   }
 
   public moveUp(): boolean {
-    return this.selectNode(this.getSelectedNode()?.getPreviousVisibleNode());
+    return this.goToNode(this.getCurrentNode()?.getPreviousVisibleNode());
   }
 
   // Activate the node, for example to open its edit page.
@@ -75,6 +99,28 @@ export default class KeyHandler {
     return true;
   }
 
+  // No node is selected. These keys select the focused node, which is
+  // usually the first node, see TreeElement.updateTabStop.
+  private getCurrentNode(): Node | null {
+    return this.multiSelect ? this.getActiveNode() : this.getSelectedNode();
+  }
+
+  // Move to the node: select it, or with multiSelect focus it.
+  // Result: there was a node to move to.
+  private goToNode(node?: Node | null): boolean {
+    if (!node) {
+      return false;
+    }
+
+    if (this.multiSelect) {
+      this.focusNode(node);
+    } else {
+      this.originalSelectNode(node);
+    }
+
+    return true;
+  }
+
   private handleArrowKey(key: string): boolean {
     switch (key) {
       case "ArrowDown": {
@@ -99,6 +145,12 @@ export default class KeyHandler {
     }
   }
 
+  private handleKey(key: string, focusedNode: Node): boolean {
+    return this.getCurrentNode()
+      ? this.handleArrowKey(key)
+      : this.handleKeyWithoutSelection(key, focusedNode);
+  }
+
   private handleKeyDown = (e: KeyboardEvent): void => {
     const focusedNode = this.getFocusedNode();
 
@@ -108,29 +160,37 @@ export default class KeyHandler {
 
     let isKeyHandled: boolean;
 
-    const selectedNode = this.getSelectedNode();
-
     switch (e.key) {
+      case " ": {
+        isKeyHandled = this.multiSelect
+          ? this.toggle(focusedNode)
+          : this.handleKey(e.key, focusedNode);
+        break;
+      }
+
       case "End": {
-        isKeyHandled = this.selectNode(this.getTree()?.getLastChild());
+        isKeyHandled = this.goToNode(this.getTree()?.getLastChild());
         break;
       }
 
       case "Enter": {
         // Without a selected node, activate the focused node
-        isKeyHandled = this.activate(selectedNode ?? focusedNode, e);
+        isKeyHandled = this.activate(
+          this.multiSelect
+            ? focusedNode
+            : (this.getSelectedNode() ?? focusedNode),
+          e,
+        );
         break;
       }
 
       case "Home": {
-        isKeyHandled = this.selectNode(this.getTree()?.children[0]);
+        isKeyHandled = this.goToNode(this.getTree()?.children[0]);
         break;
       }
 
       default: {
-        isKeyHandled = selectedNode
-          ? this.handleArrowKey(e.key)
-          : this.handleKeyWithoutSelection(e.key, focusedNode);
+        isKeyHandled = this.handleKey(e.key, focusedNode);
       }
     }
 
@@ -139,14 +199,12 @@ export default class KeyHandler {
     }
   };
 
-  // No node is selected. These keys select the focused node, which is
-  // usually the first node, see TreeElement.updateTabStop.
   private handleKeyWithoutSelection(key: string, focusedNode: Node): boolean {
     switch (key) {
       case " ":
       case "ArrowDown":
       case "ArrowRight": {
-        return this.selectNode(focusedNode);
+        return this.goToNode(focusedNode);
       }
 
       default: {
@@ -156,48 +214,40 @@ export default class KeyHandler {
   }
 
   private moveLeft(): boolean {
-    const selectedNode = this.getSelectedNode();
+    const currentNode = this.getCurrentNode();
 
     /* istanbul ignore if */
-    if (!selectedNode) {
+    if (!currentNode) {
       return false;
     }
 
-    if (selectedNode.isFolder() && selectedNode.is_open) {
+    if (currentNode.isFolder() && currentNode.is_open) {
       // Left on an open node closes the node
-      void this.closeNode(selectedNode);
+      void this.closeNode(currentNode);
       return true;
     }
     // Left on a closed or end node moves focus to the node's parent
-    return this.selectNode(selectedNode.getParent());
+    return this.goToNode(currentNode.getParent());
   }
 
   private moveRight(): boolean {
-    const selectedNode = this.getSelectedNode();
+    const currentNode = this.getCurrentNode();
 
-    if (selectedNode?.isFolder()) {
+    if (currentNode?.isFolder()) {
       // folder node
-      if (selectedNode.is_open) {
+      if (currentNode.is_open) {
         // Right moves to the first child of an open node
-        return this.selectNode(selectedNode.getNextVisibleNode());
+        return this.goToNode(currentNode.getNextVisibleNode());
       }
       // Right expands a closed node
-      void this.openNode(selectedNode);
+      void this.openNode(currentNode);
       return true;
     }
     return false;
   }
 
-  /* Select the node.
-   * Don't do anything if the node is null.
-   * Result: a different node was selected.
-   */
-  private selectNode(node?: Node | null): boolean {
-    if (node) {
-      this.originalSelectNode(node);
-
-      return true;
-    }
-    return false;
+  private toggle(node: Node): boolean {
+    this.toggleNodeInSelection(node);
+    return true;
   }
 }

package/src/methodTypes.ts

@@ -6,6 +6,10 @@ export type AddToSelection = (node: Node) => void;
 
 export type CloseNode = (node: Node) => Promise<void>;
 
+export type FocusNode = (node: Node) => void;
+
+export type GetActiveNode = () => Node | null;
+
 export type GetFocusedNode = () => Node | null;
 
 export type GetNodeById = (nodeId: NodeId) => Node | null;
@@ -34,6 +38,8 @@ export type RemoveFromSelection = (node: Node) => void;
 
 export type SelectNode = (node: Node) => void;
 
+export type ToggleNodeInSelection = (node: Node) => void;
+
 // Trigger an event. Return if the event is processed (true) or cancelled (false).
 export type TriggerEvent = <Name extends TreeEventName>(
   eventName: Name,

package/src/nodeElement/folderElement.ts

@@ -25,6 +25,7 @@ class FolderElement extends NodeElement {
     classNames,
     closedIconElement,
     getScrollLeft,
+    multiSelect,
     node,
     openedIconElement,
     renderChildren,
@@ -35,6 +36,7 @@ class FolderElement extends NodeElement {
     super({
       classNames,
       getScrollLeft,
+      multiSelect,
       node,
       tabIndex,
       treeElement,
@@ -84,8 +86,7 @@ class FolderElement extends NodeElement {
 
     this.element.classList.add(this.classNames.closed);
 
-    const titleSpan = this.getTitleSpan();
-    titleSpan.setAttribute("aria-expanded", "false");
+    this.element.setAttribute("aria-expanded", "false");
 
     this.triggerEvent("tree.close", {
       node: this.node,
@@ -132,8 +133,7 @@ class FolderElement extends NodeElement {
 
     this.element.classList.remove(this.classNames.closed);
 
-    const titleSpan = this.getTitleSpan();
-    titleSpan.setAttribute("aria-expanded", "true");
+    this.element.setAttribute("aria-expanded", "true");
 
     this.triggerEvent("tree.open", {
       node: this.node,

package/src/nodeElement/index.ts

@@ -9,6 +9,10 @@ import GhostDropHint from "./ghostDropHint";
 export interface NodeElementParams {
   classNames: ClassNames;
   getScrollLeft: GetScrollLeft;
+  /* With multiSelect the focus moves independently of the selection, so
+   * selecting doesn't change the tabindex or the focus.
+   */
+  multiSelect?: boolean;
   node: Node;
   tabIndex?: number;
   treeElement: HTMLElement;
@@ -19,18 +23,21 @@ class NodeElement {
   public node: Node;
   protected classNames: ClassNames;
   private getScrollLeft: GetScrollLeft;
+  private multiSelect: boolean;
   private tabIndex?: number;
   private treeElement: HTMLElement;
 
   constructor({
     classNames,
     getScrollLeft,
+    multiSelect = false,
     node,
     tabIndex,
     treeElement,
   }: NodeElementParams) {
     this.classNames = classNames;
     this.getScrollLeft = getScrollLeft;
+    this.multiSelect = multiSelect;
     this.node = node;
     this.tabIndex = tabIndex;
     this.treeElement = treeElement;
@@ -52,16 +59,20 @@ class NodeElement {
 
     this.element.classList.remove(this.classNames.selected);
 
-    const titleSpan = this.getTitleSpan();
+    // Only a multiselect tree marks the nodes that are not selected
+    if (this.multiSelect) {
+      this.element.setAttribute("aria-selected", "false");
+      return;
+    }
+
+    this.element.removeAttribute("aria-selected");
 
     // Check for null or undefined
     if (this.tabIndex != null) {
-      titleSpan.setAttribute("tabindex", "-1");
+      this.element.setAttribute("tabindex", "-1");
     }
 
-    titleSpan.setAttribute("aria-selected", "false");
-
-    titleSpan.blur();
+    this.element.blur();
   }
 
   public select(mustSetFocus: boolean): void {
@@ -70,28 +81,20 @@ class NodeElement {
     }
 
     this.element.classList.add(this.classNames.selected);
+    this.element.setAttribute("aria-selected", "true");
 
-    const titleSpan = this.getTitleSpan();
     const tabIndex = this.tabIndex;
 
     // Check for null or undefined
-    if (tabIndex != null) {
-      titleSpan.setAttribute("tabindex", tabIndex.toString());
+    if (tabIndex != null && !this.multiSelect) {
+      this.element.setAttribute("tabindex", tabIndex.toString());
     }
 
-    titleSpan.setAttribute("aria-selected", "true");
-
     if (mustSetFocus) {
-      titleSpan.focus();
+      this.element.focus();
     }
   }
 
-  protected getTitleSpan(): HTMLSpanElement {
-    return this.element.querySelector(
-      `:scope > .${this.classNames.element} > span.${this.classNames.title}`,
-    ) as HTMLSpanElement;
-  }
-
   protected getUl(): HTMLUListElement | null {
     return this.element.querySelector(":scope > ul");
   }

package/src/options.ts

@@ -151,6 +151,19 @@ export interface TreeElementOptions {
    * @group Selection
    */
   keyboardSupport: boolean;
+  /**
+   * Let the user select multiple nodes: a click adds a node to the
+   * selection, or removes it when it is selected. The arrow keys move the
+   * focus instead of the selection, and `Space` adds the focused node or
+   * removes it. See [Selection](/guide/selection#multiple-nodes).
+   *
+   * Set it in the constructor; changing it with `setOption` is not
+   * supported.
+   *
+   * @defaultValue `false`
+   * @group Selection
+   */
+  multiSelect: boolean;
   /**
    * The class used to create nodes. Subclass [`Node`](/reference/node) to
    * add your own methods. The `Node` class is not exposed on the global