tree-element 0.2.0 → 0.3.0

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { ClassNames } from "./classNames";
-import type { MoveInfo, TreeEvent, TreeEventName, TreeEvents } from "./events";
+import type { TreeEventName, TreeEvents } from "./events";
 import type { PositionInfo } from "./mouseUtils";
 import type { NodeData, NodeId, Position } from "./node";
 import type { TreeElementOptions } from "./options";
@@ -28,19 +28,6 @@ import __version__ from "./version";
 // the submodules directly, because those are not exposed in package.json.
 // Type only, so that the iife build keeps exposing the TreeElement class itself
 // as its global, instead of an object of named exports.
-export type {
-  MoveInfo,
-  Node,
-  NodeData,
-  NodeId,
-  Position,
-  SavedState,
-  SelectNodeOptions,
-  TreeElementOptions,
-  TreeEvent,
-  TreeEventName,
-  TreeEvents,
-};
 
 export type TriggerEventProvider = (
   element: HTMLElement,
@@ -49,7 +36,9 @@ export type TriggerEventProvider = (
 ) => boolean;
 
 interface TreeElementParams extends Partial<TreeElementOptions> {
-  /** The element the tree is rendered into. Its content is replaced. */
+  /**
+  The element the tree is rendered into. Its content is replaced.
+  */
   htmlElement: HTMLElement;
   /** Replaces how events are dispatched. It must return whether the event
    * was not cancelled. This exists for tests and for integrating with
@@ -61,6 +50,7 @@ export default class TreeElement {
   private classNames: ClassNames;
   private dataLoader: DataLoader;
   private dndHandler: DragAndDropHandler;
+  private fallbackTabStop: HTMLElement | null;
   private htmlElement: HTMLElement;
   private isInitialized: boolean;
   private keyHandler: KeyHandler;
@@ -74,7 +64,9 @@ export default class TreeElement {
   private tree: Node;
   private triggerEventProvider: TriggerEventProvider;
 
-  /** @hidden */
+  /**
+  @hidden
+  */
   constructor({
     htmlElement,
     overrideTriggerEventProvider,
@@ -89,8 +81,11 @@ export default class TreeElement {
     this.isInitialized = false;
     this.tree = new Node({}, true);
     this.nodeMap = new WeakMap();
+    this.fallbackTabStop = null;
 
     const {
+      ariaLabel,
+      ariaLabelledBy,
       autoEscape,
       buttonLeft,
       closedIcon,
@@ -118,10 +113,10 @@ export default class TreeElement {
     const closeNode = this.closeNode.bind(this);
     const getNodeElement = this.getNodeElement.bind(this);
     const getNodeElementForNode = this.getNodeElementForNode.bind(this);
+    const getFocusedNode = this.getFocusedNode.bind(this);
     const getNodeById = this.getNodeById.bind(this);
     const getSelectedNode = this.getSelectedNode.bind(this);
     const getTree = this.getTree.bind(this);
-    const isFocusOnTree = this.isFocusOnTree.bind(this);
     const loadData = this.loadData.bind(this);
     const openNode = this.openNode.bind(this);
     const openParents = this.openParents.bind(this);
@@ -130,6 +125,7 @@ export default class TreeElement {
     const setNodeElement = this.setNodeElement.bind(this);
     const treeElement = this.htmlElement;
     const triggerEvent = this.triggerEvent.bind(this);
+    const updateTabStop = this.updateTabStop.bind(this);
 
     const saveState = () => {
       saveStateHandler.saveState();
@@ -143,6 +139,7 @@ export default class TreeElement {
       openParents,
       saveState,
       triggerEvent,
+      updateTabStop,
     });
 
     const addToSelection =
@@ -208,14 +205,18 @@ export default class TreeElement {
 
     const keyHandler = new KeyHandler({
       closeNode,
+      getFocusedNode,
       getSelectedNode,
-      isFocusOnTree,
+      getTree,
       keyboardSupport,
       openNode,
       selectNode,
+      triggerEvent,
     });
 
     const renderer = new ElementsRenderer({
+      ariaLabel,
+      ariaLabelledBy,
       autoEscape,
       buttonLeft,
       classNames,
@@ -320,12 +321,13 @@ export default class TreeElement {
    * @param mustSetFocus - Move the focus to the node. Default `true`.
    * @group Selection
    */
-  public addToSelection(node: Node, mustSetFocus?: boolean) {
+  public addToSelection(node: Node, mustSetFocus = true) {
     this.selectNodeHandler.addToSelection(node);
     this.openParents(node);
 
-    this.getNodeElementForNode(node).select(mustSetFocus ?? true);
+    this.getNodeElementForNode(node).select(mustSetFocus);
 
+    this.updateTabStop();
     this.saveState();
   }
 
@@ -349,20 +351,29 @@ export default class TreeElement {
   }
 
   /**
-   * Closes a folder.
+   * Closes a folder. Await the promise when you need to know the closing
+   * animation has finished.
+   *
+   * @example
+   * ```js
+   * await tree.closeNode(node);
+   * console.log("closed");
+   * ```
    *
    * @param slide - Override the `slide` option for this call.
    * @group Opening and closing
    */
-  public closeNode(node: Node, slide?: boolean): void {
-    if (node.isFolder() || node.isEmptyFolder) {
-      this.createFolderElement(node).close(
-        slide ?? this.options.slide,
-        this.options.animationSpeed,
-      );
-
-      this.saveState();
+  public async closeNode(node: Node, slide?: boolean): Promise<void> {
+    if (!(node.isFolder() || node.isEmptyFolder)) {
+      return;
     }
+
+    await this.createFolderElement(node).close(
+      slide ?? this.options.slide,
+      this.options.animationSpeed,
+    );
+
+    this.saveState();
   }
 
   /**
@@ -391,11 +402,7 @@ export default class TreeElement {
       `li.${this.classNames.common}`,
     );
 
-    if (liElement) {
-      return this.nodeMap.get(liElement) ?? null;
-    } else {
-      return null;
-    }
+    return liElement ? (this.nodeMap.get(liElement) ?? null) : null;
   }
 
   /**
@@ -704,6 +711,7 @@ export default class TreeElement {
     this.selectNodeHandler.removeFromSelection(node);
 
     this.getNodeElementForNode(node).deselect();
+    this.updateTabStop();
     this.saveState();
   }
 
@@ -752,7 +760,11 @@ export default class TreeElement {
       return;
     }
 
-    this.selectNodeHandler.selectSingleNode(node, options);
+    // Unlike a click, selecting the selected node again keeps it selected
+    this.selectNodeHandler.selectSingleNode(node, {
+      mustToggle: false,
+      ...options,
+    });
   }
 
   /**
@@ -778,18 +790,20 @@ export default class TreeElement {
   }
 
   /**
-   * Closes an open node and opens a closed one.
+   * Closes an open node and opens a closed one. Await the promise when you
+   * need to know the node is really open or closed, like with `openNode` and
+   * `closeNode`.
    *
    * @param slide - Override the `slide` option for this call.
    * @group Opening and closing
    */
-  public toggle(node: Node, slide: boolean | null = null) {
+  public async toggle(node: Node, slide: boolean | null = null): Promise<void> {
     const mustSlide = slide ?? this.options.slide;
 
     if (node.is_open) {
-      this.closeNode(node, mustSlide);
+      await this.closeNode(node, mustSlide);
     } else {
-      void this.openNode(node, mustSlide);
+      await this.openNode(node, mustSlide);
     }
   }
 
@@ -835,7 +849,7 @@ export default class TreeElement {
     if (
       typeof data === "object" &&
       data.children &&
-      data.children instanceof Array
+      Array.isArray(data.children)
     ) {
       node.removeChildren();
 
@@ -847,6 +861,34 @@ export default class TreeElement {
     this.refreshElements(node);
   }
 
+  // Open the nodes up to the autoOpen level. A folder that is loaded on
+  // demand is fetched first, and its children are opened when the data has
+  // arrived.
+  private async autoOpenNodesOnDemand(): Promise<void> {
+    const maxLevel = this.getAutoOpenMaxLevel();
+
+    const openNodes = async (): Promise<void> => {
+      const loading: Promise<void>[] = [];
+
+      this.tree.iterate((node: Node, level: number) => {
+        if (node.load_on_demand) {
+          if (!node.is_loading) {
+            loading.push(this.openNode(node, false).then(openNodes));
+          }
+
+          return false;
+        }
+        void this.openNode(node, false);
+
+        return level !== maxLevel;
+      });
+
+      await Promise.all(loading);
+    };
+
+    await openNodes();
+  }
+
   private createFolderElement(node: Node) {
     const classNames = this.classNames;
     const closedIconElement = this.renderer.closedIconElement;
@@ -854,11 +896,19 @@ export default class TreeElement {
       this.scrollHandler,
     );
     const openedIconElement = this.renderer.openedIconElement;
-    const renderChildren = this.renderer.renderChildren.bind(this.renderer);
     const tabIndex = this.options.tabIndex;
     const treeElement = this.htmlElement;
     const triggerEvent = this.triggerEvent.bind(this);
 
+    // A selected node in a closed folder is rendered when the folder is
+    // opened, which can be after it was selected. It becomes the tab stop
+    // then, so the fallback tab stop must go.
+    const renderChildren = (folder: Node) => {
+      const ul = this.renderer.renderChildren(folder);
+      this.updateTabStop();
+      return ul;
+    };
+
     return new FolderElement({
       classNames,
       closedIconElement,
@@ -896,13 +946,7 @@ export default class TreeElement {
   private createRequestUrl(node?: Node): null | RequestUrl {
     const dataUrl = this.options.dataUrl;
 
-    let url;
-
-    if (typeof dataUrl === "function") {
-      url = dataUrl(node);
-    } else {
-      url = dataUrl;
-    }
+    const url = typeof dataUrl === "function" ? dataUrl(node) : dataUrl;
 
     if (!url) {
       return null;
@@ -944,9 +988,11 @@ export default class TreeElement {
   private getAutoOpenMaxLevel(): number {
     if (this.options.autoOpen === true) {
       return -1;
-    } else if (typeof this.options.autoOpen === "number") {
+    }
+    if (typeof this.options.autoOpen === "number") {
       return this.options.autoOpen;
-    } else if (typeof this.options.autoOpen === "string") {
+    }
+    if (typeof this.options.autoOpen === "string") {
       return parseInt(this.options.autoOpen, 10);
     }
 
@@ -954,27 +1000,55 @@ export default class TreeElement {
     return 0;
   }
 
-  private getNodeElement(element: HTMLElement): NodeElement | null {
-    const node = this.getNode(element);
-    if (node) {
-      return this.getNodeElementForNode(node);
-    } else {
+  // 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;
+  }
+
+  // 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") {
       return null;
     }
+
+    const node = this.getNode(activeElement as HTMLElement);
+    return node?.tree === this.tree ? node : null;
+  }
+
+  private getNodeElement(element: HTMLElement): NodeElement | null {
+    const node = this.getNode(element);
+    return node ? this.getNodeElementForNode(node) : null;
   }
 
   private getNodeElementForNode(node: Node): NodeElement {
-    if (node.isFolder()) {
-      return this.createFolderElement(node);
-    } else {
-      return this.createNodeElement(node);
-    }
+    return node.isFolder()
+      ? this.createFolderElement(node)
+      : this.createNodeElement(node);
   }
 
   private getNodeIdToBeSelected(): NodeId | null {
     return this.saveStateHandler.getNodeIdToBeSelected();
   }
 
+  private hasRenderedSelectedNode(): boolean {
+    return this.getSelectedNodes().some((node) => Boolean(node.element));
+  }
+
   private initData(): void {
     if (this.options.data) {
       this.loadData(this.options.data);
@@ -991,10 +1065,12 @@ export default class TreeElement {
 
   private initTree(data: NodeData[]): void {
     const doInit = (): void => {
-      if (!this.isInitialized) {
-        this.isInitialized = true;
-        this.triggerEvent("tree.init");
+      if (this.isInitialized) {
+        return;
       }
+
+      this.isInitialized = true;
+      this.triggerEvent("tree.init");
     };
 
     this.tree = new this.options.nodeClass(null, true, this.options.nodeClass);
@@ -1017,31 +1093,15 @@ export default class TreeElement {
 
   // Does an HTML element of the tree have the focus?
   private isFocusOnTree(): boolean {
-    const activeElement = document.activeElement;
-
-    /* istanbul ignore if */
-    if (!activeElement) {
-      return false;
-    }
-
-    // The keyboard must still work for input elements.
-    const tagName = activeElement.tagName;
-    if (tagName !== "A" && tagName !== "SPAN") {
-      return false;
-    }
-
-    const node = this.getNode(activeElement as HTMLElement);
-    return node?.tree === this.tree;
+    return this.getFocusedNode() !== null;
   }
 
   private isSelectedNodeInSubtree(subtree: Node): boolean {
     const selectedNode = this.getSelectedNode();
 
-    if (!selectedNode) {
-      return false;
-    } else {
-      return subtree === selectedNode || subtree.isParentOf(selectedNode);
-    }
+    return selectedNode
+      ? subtree === selectedNode || subtree.isParentOf(selectedNode)
+      : false;
   }
 
   private async loadFolderOnDemand(node: Node, slide: boolean): Promise<void> {
@@ -1049,6 +1109,13 @@ export default class TreeElement {
 
     await this.loadDataFromUrl(undefined, node);
 
+    // Loading failed, or there is no url. Opening the node now would load it
+    // again, without end. Leave it closed so the user can try again.
+    if (node.load_on_demand) {
+      node.is_loading = false;
+      return;
+    }
+
     await this.openNode(node, slide);
   }
 
@@ -1062,11 +1129,9 @@ export default class TreeElement {
   }
 
   private mouseCapture(positionInfo: PositionInfo): boolean | null {
-    if (!this.options.dragAndDrop) {
-      return false;
-    }
-
-    return this.dndHandler.mouseCapture(positionInfo);
+    return this.options.dragAndDrop
+      ? this.dndHandler.mouseCapture(positionInfo)
+      : false;
   }
 
   private mouseDrag(positionInfo: PositionInfo): boolean {
@@ -1082,6 +1147,7 @@ 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;
     }
@@ -1123,6 +1189,8 @@ export default class TreeElement {
       this.selectCurrentNode(mustSetFocus);
     }
 
+    this.updateTabStop();
+
     this.triggerEvent("tree.refresh");
   }
 
@@ -1132,10 +1200,12 @@ export default class TreeElement {
 
   private selectCurrentNode(mustSetFocus: boolean): void {
     const node = this.getSelectedNode();
-    if (node) {
-      const nodeElement = this.getNodeElementForNode(node);
-      nodeElement.select(mustSetFocus);
+    if (!node) {
+      return;
     }
+
+    const nodeElement = this.getNodeElementForNode(node);
+    nodeElement.select(mustSetFocus);
   }
 
   // Set initial state, either by restoring the state or auto-opening nodes
@@ -1145,14 +1215,13 @@ export default class TreeElement {
       // result: is state restored, must load on demand?
       const state = this.saveStateHandler.getStateFromStorage();
 
-      if (!state) {
-        return [false, false];
-      } else {
+      if (state) {
         const mustLoadOnDemand = this.saveStateHandler.setInitialState(state);
 
         // return true: the state is restored
         return [true, mustLoadOnDemand];
       }
+      return [false, false];
     };
 
     const autoOpenNodes = (): boolean => {
@@ -1168,12 +1237,12 @@ export default class TreeElement {
         if (node.load_on_demand) {
           mustLoadOnDemand = true;
           return false;
-        } else if (!node.hasChildren()) {
-          return false;
-        } else {
+        }
+        if (node.hasChildren()) {
           node.is_open = true;
           return level !== maxLevel;
         }
+        return false;
       });
 
       return mustLoadOnDemand;
@@ -1190,60 +1259,13 @@ export default class TreeElement {
 
   // Set the initial state for nodes that are loaded on demand
   private async setInitialStateOnDemand(): Promise<void> {
-    return new Promise((resolve) => {
-      const restoreState = (): boolean => {
-        const state = this.saveStateHandler.getStateFromStorage();
-
-        if (!state) {
-          return false;
-        } else {
-          void this.saveStateHandler.setInitialStateOnDemand(state).then(() => {
-            resolve();
-          });
-
-          return true;
-        }
-      };
-
-      const autoOpenNodes = (): void => {
-        const maxLevel = this.getAutoOpenMaxLevel();
-        let loadingCount = 0;
-
-        const loadAndOpenNode = (node: Node): void => {
-          loadingCount += 1;
-          void this.openNode(node, false).then(() => {
-            loadingCount -= 1;
-            openNodes();
-          });
-        };
-
-        const openNodes = (): void => {
-          this.tree.iterate((node: Node, level: number) => {
-            if (node.load_on_demand) {
-              if (!node.is_loading) {
-                loadAndOpenNode(node);
-              }
-
-              return false;
-            } else {
-              void this.openNode(node, false);
-
-              return level !== maxLevel;
-            }
-          });
-
-          if (loadingCount === 0) {
-            resolve();
-          }
-        };
-
-        openNodes();
-      };
+    const state = this.saveStateHandler.getStateFromStorage();
 
-      if (!restoreState()) {
-        autoOpenNodes();
-      }
-    });
+    if (state) {
+      await this.saveStateHandler.setInitialStateOnDemand(state);
+    } else {
+      await this.autoOpenNodesOnDemand();
+    }
   }
 
   // Set this HTML element to this node in the node map.
@@ -1257,4 +1279,42 @@ export default class TreeElement {
   ): boolean {
     return this.triggerEventProvider(this.htmlElement, eventName, values);
   }
+
+  /* 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.
+   */
+  private updateTabStop(): void {
+    const tabIndex = this.options.tabIndex;
+    const previousTabStop = this.fallbackTabStop;
+    const tabStop =
+      tabIndex == null || this.hasRenderedSelectedNode()
+        ? null
+        : this.getFirstTitleSpan();
+
+    if (
+      previousTabStop &&
+      previousTabStop !== tabStop &&
+      previousTabStop.getAttribute("aria-selected") !== "true"
+    ) {
+      previousTabStop.setAttribute("tabindex", "-1");
+    }
+
+    if (tabStop && tabIndex != null) {
+      tabStop.setAttribute("tabindex", String(tabIndex));
+    }
+
+    this.fallbackTabStop = tabStop;
+  }
 }
+
+export {
+  type MoveInfo,
+  type TreeEvent,
+  type TreeEventName,
+  type TreeEvents,
+} from "./events";
+export { type Node, type NodeData, type NodeId, type Position } from "./node";
+export { type TreeElementOptions } from "./options";
+export { type SavedState } from "./saveStateHandler";
+export { type SelectNodeOptions } from "./selectNodeHandler";