tree-element 0.4.0 → 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";
@@ -109,7 +110,6 @@ export default class TreeElement {
       rtl,
       saveState: saveStateOption,
       showEmptyFolder,
-      slide,
       tabIndex,
     } = this.options;
 
@@ -215,7 +215,6 @@ export default class TreeElement {
       openFolderDelay,
       openNode,
       refreshElements,
-      slide,
       treeElement,
       triggerEvent,
     });
@@ -325,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
@@ -512,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
@@ -531,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
@@ -647,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.
    *
@@ -667,7 +667,7 @@ export default class TreeElement {
       openedNode: Node,
       slideOption: boolean,
     ): Promise<void> => {
-      if (!node.children.length) {
+      if (!openedNode.children.length) {
         return;
       }
 
@@ -797,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
+    }
   }
 
   /**
@@ -837,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
    */
@@ -851,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
@@ -920,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);
@@ -940,11 +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,
@@ -1055,14 +1086,11 @@ export default class TreeElement {
   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 !== "LI" && 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;
     }
 
@@ -1125,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();
@@ -1135,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);
@@ -1143,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;
 
@@ -1206,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) {
@@ -1229,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();
@@ -1245,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
@@ -1319,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);
@@ -1374,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";

package/src/keyHandler.ts

@@ -93,6 +93,26 @@ export default class KeyHandler {
     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.
   private activate(node: Node, originalEvent: KeyboardEvent): boolean {
     this.triggerEvent("tree.activate", { node, originalEvent });

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,33 +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,
@@ -42,8 +41,7 @@ class FolderElement extends NodeElement {
       treeElement,
     });
 
-    this.closedIconElement = closedIconElement;
-    this.openedIconElement = openedIconElement;
+    this.icons = icons;
     this.renderChildren = renderChildren;
     this.triggerEvent = triggerEvent;
   }
@@ -58,39 +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);
-
-    this.element.setAttribute("aria-expanded", "false");
-
-    this.triggerEvent("tree.close", {
-      node: this.node,
-    });
+    this.triggerEvent("tree.close", { node: this.node });
   }
 
   public async open(
@@ -103,41 +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);
-
-    this.element.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;