tree-element 0.3.2 → 0.4.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,31 @@ 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());
+  }
+
+  // Change keyboardSupport after construction
+  public setKeyboardSupport(keyboardSupport: boolean): void {
+    if (keyboardSupport === this.keyboardSupport) {
+      return;
+    }
+
+    this.keyboardSupport = keyboardSupport;
+
+    if (keyboardSupport) {
+      document.addEventListener("keydown", this.handleKeyDown);
+    } else {
+      document.removeEventListener("keydown", this.handleKeyDown);
+    }
+  }
+
+  // Change multiSelect after construction
+  public setMultiSelect(multiSelect: boolean): void {
+    this.multiSelect = multiSelect;
   }
 
   // Activate the node, for example to open its edit page.
@@ -75,6 +119,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 +165,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 +180,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 +219,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 +234,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/mouseHandler.ts

@@ -180,7 +180,7 @@ class MouseHandler {
     }
   };
 
-  private handleContextmenu = (e: MouseEvent) => {
+  private handleContextmenu = (e: MouseEvent): void => {
     if (!e.target) {
       return;
     }
@@ -189,21 +189,23 @@ class MouseHandler {
       `ul.${this.classNames.tree} .${this.classNames.element}`,
     );
 
-    if (div) {
-      const node = this.getNode(div);
-      if (node) {
-        e.preventDefault();
-        e.stopPropagation();
+    if (!div) {
+      return;
+    }
 
-        this.triggerEvent("tree.contextmenu", {
-          node,
-          originalEvent: e,
-        });
-        return false;
-      }
+    const node = this.getNode(div);
+
+    if (!node) {
+      return;
     }
 
-    return null;
+    e.preventDefault();
+    e.stopPropagation();
+
+    this.triggerEvent("tree.contextmenu", {
+      node,
+      originalEvent: e,
+    });
   };
 
   private handleDblclick = (e: MouseEvent): void => {

package/src/node.ts

@@ -28,14 +28,14 @@ type IterateCallback = (node: Node, level: number) => boolean;
  *
  * @groupDescription Searching
  * These work on any node, and search that node's subtree. Called on the root
- * node, they search the whole tree — which is what the tree's own methods of
+ * node, they search the whole tree—which is what the tree's own methods of
  * the same name do.
  *
  * @groupDescription Changing the tree
  * ::: warning
  * These methods change the data without re-rendering. The tree's
- * [methods](/reference/methods) — `appendNode`, `removeNode`, `moveNode` and
- * friends — do the same and refresh the display, so prefer those. If you do
+ * [methods](/reference/methods)—`appendNode`, `removeNode`, `moveNode` and
+ * friends—do the same and refresh the display, so prefer those. If you do
  * use these, call `tree.refresh()` afterwards.
  * :::
  */
@@ -85,7 +85,7 @@ export class Node {
   */
   public nodeClass?: typeof Node;
   /**
-  The parent; `null` for the root node.
+  The parent, or `null` for the root node.
   */
   public parent: Node | null;
   /**
@@ -191,7 +191,9 @@ export class Node {
   }
 
   /**
-   * Inserts a new parent between this node and its current parent.
+   * Inserts a new parent between this node and its current parent. Its
+   * siblings move along: the new node takes all children of the current
+   * parent, and becomes its only child.
    *
    * @returns The new node, or `null` when the node has no parent.
    * @group Changing the tree
@@ -268,7 +270,7 @@ export class Node {
    * Returns the subtree as plain data, ready for `JSON.stringify`.
    * Internal properties (`parent`, `children`, `element`, `tree`,
    * `idMapping`, `nodeClass`, `load_on_demand`, `isEmptyFolder`) are left
-   * out; your own properties are kept.
+   * out. Your own properties are kept.
    *
    * ```js
    * tree.getTree().getData();
@@ -384,7 +386,7 @@ export class Node {
   }
 
   /**
-   * Like `getNextNode`, but skipping nodes inside closed folders — this is
+   * Like `getNextNode`, but skipping nodes inside closed folders. This is
    * what the arrow keys use.
    *
    * @group Moving around the tree
@@ -472,7 +474,7 @@ export class Node {
   }
 
   /**
-   * Returns the parent: `null` for a top-level node — the root node is not
+   * Returns the parent, or `null` for a top-level node: the root node is not
    * returned.
    *
    * @group Moving around the tree
@@ -525,8 +527,8 @@ export class Node {
   }
 
   /**
-   * Like `getPreviousNode`, but skipping nodes inside closed folders —
-   * this is what the arrow keys use.
+   * Like `getPreviousNode`, but skipping nodes inside closed folders.
+   * This is what the arrow keys use.
    *
    * @group Moving around the tree
    */

package/src/nodeElement/folderElement.ts

@@ -1,32 +1,32 @@
 import type { AnimationSpeed } from "../animation";
+import type { FolderIcons } from "../folderOpenState";
 import type { TriggerEvent } from "../methodTypes";
 import type { Node, Position } from "../node";
 import type { NodeElementParams } from "./index";
 
 import { slideDown, slideUp } from "../animation";
+import { setFolderLiOpenState, setTogglerOpenState } from "../folderOpenState";
 import NodeElement from "./index";
 
 export type RenderChildren = (node: Node) => HTMLUListElement | null;
 
 interface FolderElementParams extends NodeElementParams {
-  closedIconElement?: globalThis.Node;
-  openedIconElement?: globalThis.Node;
+  icons: FolderIcons;
   renderChildren: RenderChildren;
   triggerEvent: TriggerEvent;
 }
 
 class FolderElement extends NodeElement {
-  private closedIconElement?: globalThis.Node;
-  private openedIconElement?: globalThis.Node;
+  private icons: FolderIcons;
   private renderChildren: RenderChildren;
   private triggerEvent: TriggerEvent;
 
   constructor({
     classNames,
-    closedIconElement,
     getScrollLeft,
+    icons,
+    multiSelect,
     node,
-    openedIconElement,
     renderChildren,
     tabIndex,
     treeElement,
@@ -35,13 +35,13 @@ class FolderElement extends NodeElement {
     super({
       classNames,
       getScrollLeft,
+      multiSelect,
       node,
       tabIndex,
       treeElement,
     });
 
-    this.closedIconElement = closedIconElement;
-    this.openedIconElement = openedIconElement;
+    this.icons = icons;
     this.renderChildren = renderChildren;
     this.triggerEvent = triggerEvent;
   }
@@ -56,40 +56,13 @@ class FolderElement extends NodeElement {
 
     this.node.is_open = false;
 
-    if (!this.isRendered()) {
-      this.triggerEvent("tree.close", { node: this.node });
-      return;
-    }
-
-    const button = this.getButton();
-    button.classList.add(this.classNames.closed);
-    button.replaceChildren();
-
-    const closedIconElement = this.closedIconElement;
-
-    if (closedIconElement) {
-      const icon = closedIconElement.cloneNode(true);
-      button.append(icon);
+    if (this.isRendered()) {
+      this.setButtonState(false);
+      await this.setUlState(this.getUl(), false, slide, animationSpeed);
+      this.setElementState(false);
     }
 
-    const ul = this.getUl();
-
-    if (ul) {
-      if (slide) {
-        await slideUp(ul, animationSpeed);
-      } else {
-        ul.style.display = "none";
-      }
-    }
-
-    this.element.classList.add(this.classNames.closed);
-
-    const titleSpan = this.getTitleSpan();
-    titleSpan.setAttribute("aria-expanded", "false");
-
-    this.triggerEvent("tree.close", {
-      node: this.node,
-    });
+    this.triggerEvent("tree.close", { node: this.node });
   }
 
   public async open(
@@ -102,42 +75,19 @@ class FolderElement extends NodeElement {
 
     this.node.is_open = true;
 
-    if (!this.isRendered()) {
-      // The folder is rendered open when its parent is opened
-      this.triggerEvent("tree.open", { node: this.node });
-      return;
-    }
-
-    const button = this.getButton();
-    button.classList.remove(this.classNames.closed);
-    button.replaceChildren();
-
-    const openedIconElement = this.openedIconElement;
-
-    if (openedIconElement) {
-      const icon = openedIconElement.cloneNode(true);
-      button.append(icon);
-    }
+    // A folder that is not rendered is rendered open when its parent is
+    // opened
+    if (this.isRendered()) {
+      this.setButtonState(true);
 
-    // The children are rendered the first time the folder is opened
-    const ul = this.getUl() ?? this.renderChildren(this.node);
+      // The children are rendered the first time the folder is opened
+      const ul = this.getUl() ?? this.renderChildren(this.node);
+      await this.setUlState(ul, true, slide, animationSpeed);
 
-    if (ul) {
-      if (slide) {
-        await slideDown(ul, animationSpeed);
-      } else {
-        ul.style.display = "block";
-      }
+      this.setElementState(true);
     }
 
-    this.element.classList.remove(this.classNames.closed);
-
-    const titleSpan = this.getTitleSpan();
-    titleSpan.setAttribute("aria-expanded", "true");
-
-    this.triggerEvent("tree.open", {
-      node: this.node,
-    });
+    this.triggerEvent("tree.open", { node: this.node });
   }
 
   protected mustShowBorderDropHint(position: Position): boolean {
@@ -149,6 +99,31 @@ class FolderElement extends NodeElement {
       `:scope > .${this.classNames.element} > .${this.classNames.toggler}`,
     ) as HTMLElement;
   }
+
+  private setButtonState(isOpen: boolean): void {
+    setTogglerOpenState(this.getButton(), isOpen, this.classNames, this.icons);
+  }
+
+  private setElementState(isOpen: boolean): void {
+    setFolderLiOpenState(this.element, isOpen, this.classNames);
+  }
+
+  private async setUlState(
+    ul: HTMLUListElement | null,
+    isOpen: boolean,
+    slide: boolean,
+    animationSpeed: AnimationSpeed,
+  ): Promise<void> {
+    if (!ul) {
+      return;
+    }
+
+    if (slide) {
+      await (isOpen ? slideDown : slideUp)(ul, animationSpeed);
+    } else {
+      ul.style.display = isOpen ? "block" : "none";
+    }
+  }
 }
 
 export default FolderElement;

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");
   }