tree-element 0.3.2 → 0.4.1

package/src/elementsRenderer.ts

@@ -1,9 +1,10 @@
 import type { ClassNames } from "./classNames";
+import type { FolderIcons } from "./folderOpenState";
 import type { GetTree, IsNodeSelected } from "./methodTypes";
 import type { Node } from "./node";
 import type { IconElement, OnCreateLi } from "./options";
 
-import { getBoolString } from "./util";
+import { setFolderLiOpenState, setTogglerOpenState } from "./folderOpenState";
 
 interface ElementsRendererParams {
   ariaLabel?: string;
@@ -16,6 +17,7 @@ interface ElementsRendererParams {
   getTree: GetTree;
   htmlElement: HTMLElement;
   isNodeSelected: IsNodeSelected;
+  multiSelect: boolean;
   onCreateLi?: OnCreateLi;
   openedIcon?: IconElement;
   rtl?: boolean;
@@ -36,8 +38,7 @@ interface ElementsRendererParams {
  * selected and loading classes.
  */
 export default class ElementsRenderer {
-  public closedIconElement?: globalThis.Node;
-  public openedIconElement?: globalThis.Node;
+  public icons: FolderIcons;
   private ariaLabel?: string;
   private ariaLabelledBy?: string;
   private autoEscape: boolean;
@@ -49,6 +50,7 @@ export default class ElementsRenderer {
   private groupUlTemplate: HTMLUListElement;
   private htmlElement: HTMLElement;
   private isNodeSelected: IsNodeSelected;
+  private multiSelect: boolean;
   private nodeTemplate: HTMLLIElement;
   private onCreateLi?: OnCreateLi;
   private openedFolderTemplate: HTMLLIElement;
@@ -69,6 +71,7 @@ export default class ElementsRenderer {
     getTree,
     htmlElement,
     isNodeSelected,
+    multiSelect,
     onCreateLi,
     openedIcon = "+",
     rtl,
@@ -85,19 +88,23 @@ export default class ElementsRenderer {
     this.getTree = getTree;
     this.htmlElement = htmlElement;
     this.isNodeSelected = isNodeSelected;
+    this.multiSelect = multiSelect;
     this.onCreateLi = onCreateLi;
     this.rtl = rtl;
     this.setNodeElement = setNodeElement;
     this.showEmptyFolder = showEmptyFolder;
     this.tabIndex = tabIndex;
-    this.openedIconElement = this.createButtonElement(openedIcon);
-    this.closedIconElement = this.createButtonElement(closedIcon);
-
-    this.rootUlTemplate = this.createUlTemplate(true);
-    this.groupUlTemplate = this.createUlTemplate(false);
-    this.nodeTemplate = this.createNodeTemplate();
-    this.openedFolderTemplate = this.createFolderTemplate(true);
-    this.closedFolderTemplate = this.createFolderTemplate(false);
+    this.icons = {
+      closed: this.createButtonElement(closedIcon),
+      opened: this.createButtonElement(openedIcon),
+    };
+
+    const templates = this.createTemplates();
+    this.closedFolderTemplate = templates.closedFolderTemplate;
+    this.groupUlTemplate = templates.groupUlTemplate;
+    this.nodeTemplate = templates.nodeTemplate;
+    this.openedFolderTemplate = templates.openedFolderTemplate;
+    this.rootUlTemplate = templates.rootUlTemplate;
   }
 
   public render(fromNode: Node | null): void {
@@ -112,14 +119,14 @@ export default class ElementsRenderer {
    * null when the folder is not rendered or has no children.
    */
   public renderChildren(node: Node): HTMLUListElement | null {
-    return !node.element || !node.hasChildren()
-      ? null
-      : this.createDomElements(
+    return node.element && node.hasChildren()
+      ? this.createDomElements(
           node.element,
           node.children,
           false,
           node.getLevel() + 1,
-        );
+        )
+      : null;
   }
 
   public renderFromNode(node: Node): void {
@@ -146,6 +153,50 @@ export default class ElementsRenderer {
     }
   }
 
+  /* Change dragAndDrop after construction. The rendered lists and the
+   * templates for new lists get or lose the dnd class.
+   */
+  public setDragAndDrop(dragAndDrop: boolean): void {
+    this.dragAndDrop = dragAndDrop;
+    this.updateTemplates();
+
+    for (const ul of this.htmlElement.querySelectorAll(
+      `ul.${this.classNames.common}`,
+    )) {
+      ul.classList.toggle(this.classNames.dnd, dragAndDrop);
+    }
+  }
+
+  /* Change multiSelect after construction. Only the templates are updated;
+   * the tree must be rendered again.
+   */
+  public setMultiSelect(multiSelect: boolean): void {
+    this.multiSelect = multiSelect;
+    this.updateTemplates();
+  }
+
+  /* Change tabIndex after construction. The rendered nodes and the
+   * templates for new nodes get the new tabindex. The tab stop is updated by
+   * TreeElement.updateTabStop.
+   */
+  public setTabIndex(tabIndex: number | undefined): void {
+    this.tabIndex = tabIndex;
+    this.updateTemplates();
+
+    for (const li of this.htmlElement.querySelectorAll("li[role=treeitem]")) {
+      if (tabIndex === undefined) {
+        li.removeAttribute("tabindex");
+      } else if (
+        !this.multiSelect &&
+        li.getAttribute("aria-selected") === "true"
+      ) {
+        li.setAttribute("tabindex", String(tabIndex));
+      } else {
+        li.setAttribute("tabindex", "-1");
+      }
+    }
+  }
+
   private attachNodeData(node: Node, li: HTMLElement): void {
     node.element = li;
     this.setNodeElement(li, node);
@@ -208,11 +259,11 @@ export default class ElementsRenderer {
       this.buttonLeft ? 1 : 0
     ] as HTMLSpanElement;
 
-    this.fillTitleSpan(titleSpan, node.name, isSelected, level);
+    this.fillNode(li, titleSpan, node.name, isSelected, level);
 
     if (node.is_loading) {
       li.classList.add(this.classNames.loading);
-      titleSpan.setAttribute("aria-busy", "true");
+      li.setAttribute("aria-busy", "true");
     }
 
     return li;
@@ -224,37 +275,26 @@ export default class ElementsRenderer {
    * state, so there is a template for each.
    */
   private createFolderTemplate(isOpen: boolean): HTMLLIElement {
-    const liClasses = [this.classNames.common, this.classNames.folder];
+    const li = this.createLiTemplate(
+      `${this.classNames.common} ${this.classNames.folder}`,
+    );
+    setFolderLiOpenState(li, isOpen, this.classNames);
 
-    if (!isOpen) {
-      liClasses.push(this.classNames.closed);
-    }
-
-    const li = this.createLiTemplate(liClasses.join(" "));
     const div = li.firstChild as HTMLDivElement;
 
     // The toggler is hidden from screen readers: the icon is decoration, and
     // aria-expanded on the treeitem has the open state.
     const toggler = document.createElement("span");
-    toggler.className = this.getButtonClasses(isOpen);
+    toggler.className = this.getButtonClasses();
     toggler.setAttribute("aria-hidden", "true");
-
-    const iconElement = isOpen
-      ? this.openedIconElement
-      : this.closedIconElement;
-
-    if (iconElement) {
-      toggler.append(iconElement.cloneNode(true));
-    }
+    setTogglerOpenState(toggler, isOpen, this.classNames, this.icons);
 
     if (this.buttonLeft) {
       div.append(toggler);
     }
 
     // title span
-    const titleSpan = this.createTitleSpanTemplate(true);
-    titleSpan.setAttribute("aria-expanded", getBoolString(isOpen));
-    div.append(titleSpan);
+    div.append(this.createTitleSpanTemplate(true));
 
     if (!this.buttonLeft) {
       div.append(toggler);
@@ -288,11 +328,22 @@ export default class ElementsRenderer {
 
   /*
   Create the outer part of a <li> template: li > div
+  The li is the treeitem, so the ul of its children is inside the treeitem.
   */
   private createLiTemplate(liClasses: string): HTMLLIElement {
     const li = document.createElement("li");
     li.className = liClasses;
-    li.setAttribute("role", "none");
+    li.setAttribute("role", "treeitem");
+
+    // Only a multiselect tree marks the nodes that are not selected
+    if (this.multiSelect) {
+      li.setAttribute("aria-selected", "false");
+    }
+
+    // Every node is focusable, but only the tab stop is in the tab order
+    if (this.tabIndex !== undefined) {
+      li.setAttribute("tabindex", "-1");
+    }
 
     const div = document.createElement("div");
     div.className = `${this.classNames.element} ${this.classNames.common}`;
@@ -318,7 +369,7 @@ export default class ElementsRenderer {
     const div = li.firstChild as HTMLDivElement;
     const titleSpan = div.firstChild as HTMLSpanElement;
 
-    this.fillTitleSpan(titleSpan, node.name, isSelected, level);
+    this.fillNode(li, titleSpan, node.name, isSelected, level);
 
     return li;
   }
@@ -335,6 +386,16 @@ export default class ElementsRenderer {
     return li;
   }
 
+  private createTemplates() {
+    return {
+      closedFolderTemplate: this.createFolderTemplate(false),
+      groupUlTemplate: this.createUlTemplate(false),
+      nodeTemplate: this.createNodeTemplate(),
+      openedFolderTemplate: this.createFolderTemplate(true),
+      rootUlTemplate: this.createUlTemplate(true),
+    };
+  }
+
   private createTitleSpanTemplate(isFolder: boolean): HTMLSpanElement {
     const titleSpan = document.createElement("span");
 
@@ -347,13 +408,6 @@ export default class ElementsRenderer {
     classes += ` ${this.buttonLeft ? this.classNames.titleButtonLeft : this.classNames.titleButtonRight}`;
 
     titleSpan.className = classes;
-    titleSpan.setAttribute("role", "treeitem");
-    titleSpan.setAttribute("aria-selected", "false");
-
-    // Every node is focusable, but only the tab stop is in the tab order
-    if (this.tabIndex !== undefined) {
-      titleSpan.setAttribute("tabindex", "-1");
-    }
 
     return titleSpan;
   }
@@ -391,29 +445,35 @@ export default class ElementsRenderer {
       if (this.ariaLabelledBy !== undefined) {
         ul.setAttribute("aria-labelledby", this.ariaLabelledBy);
       }
+
+      if (this.multiSelect) {
+        ul.setAttribute("aria-multiselectable", "true");
+      }
     }
 
     return ul;
   }
 
   /*
-  Set the parts of a cloned title span that differ per node
+  Set the parts of a cloned li and title span that differ per node
   */
-  private fillTitleSpan(
+  private fillNode(
+    li: HTMLLIElement,
     titleSpan: HTMLSpanElement,
     nodeName: string,
     isSelected: boolean,
     level: number,
   ): void {
-    titleSpan.setAttribute("aria-level", String(level));
+    li.setAttribute("aria-level", String(level));
 
     if (isSelected) {
-      titleSpan.setAttribute("aria-selected", "true");
+      li.setAttribute("aria-selected", "true");
 
       const tabIndex = this.tabIndex;
 
-      if (tabIndex !== undefined) {
-        titleSpan.setAttribute("tabindex", String(tabIndex));
+      // With multiSelect the tab stop is the active node, see updateTabStop
+      if (tabIndex !== undefined && !this.multiSelect) {
+        li.setAttribute("tabindex", String(tabIndex));
       }
     }
 
@@ -423,15 +483,15 @@ export default class ElementsRenderer {
       // eslint-disable-next-line no-unsanitized/property -- the user opted out of escaping with autoEscape: false
       titleSpan.innerHTML = nodeName;
     }
+
+    // The treeitem is named by its title, without the html when autoEscape
+    // is false. Otherwise the name would contain everything in the row.
+    li.setAttribute("aria-label", titleSpan.textContent);
   }
 
-  private getButtonClasses(isOpen: boolean): string {
+  private getButtonClasses(): string {
     const classes = [this.classNames.toggler, this.classNames.common];
 
-    if (!isOpen) {
-      classes.push(this.classNames.closed);
-    }
-
     if (this.buttonLeft) {
       classes.push(this.classNames.togglerLeft);
     } else {
@@ -447,4 +507,13 @@ export default class ElementsRenderer {
   private mustRenderChildren(node: Node): boolean {
     return node.hasChildren() && node.is_open === true;
   }
+
+  private updateTemplates(): void {
+    const templates = this.createTemplates();
+    this.closedFolderTemplate = templates.closedFolderTemplate;
+    this.groupUlTemplate = templates.groupUlTemplate;
+    this.nodeTemplate = templates.nodeTemplate;
+    this.openedFolderTemplate = templates.openedFolderTemplate;
+    this.rootUlTemplate = templates.rootUlTemplate;
+  }
 }

package/src/events.ts

@@ -25,7 +25,7 @@ export interface TreeEvents {
   /**
    * Dispatched once, after the tree is rendered for the first time. With
    * `dataUrl` this is after the data has arrived, so it is the moment the
-   * api is safe to use:
+   * API is safe to use:
    *
    * ```js
    * element.addEventListener("tree.init", () => {
@@ -85,7 +85,7 @@ export interface TreeEvents {
     originalEvent: MouseEvent;
   };
   /**
-   * Dispatched on a right click on a node, unless `useContextMenu` is
+   * Dispatched when a node is right-clicked, unless `useContextMenu` is
    * `false`. The browser's own menu is suppressed.
    *
    * @group Mouse
@@ -96,7 +96,7 @@ export interface TreeEvents {
   };
   /**
    * Dispatched when `Enter` is pressed on the selected node, or on the
-   * focused node when no node is selected. Use it for what a click on a
+   * focused node when no node is selected. Use it for what clicking a
    * link would do, like opening the edit page of the node:
    *
    * ```js
@@ -142,7 +142,9 @@ export interface TreeEvents {
    */
   "tree.select": {
     /**
-    The node that was selected before, if any.
+    The node that was selected before, if any. When several nodes were
+    selected, this is the first, and the others get a `tree.deselect`,
+    dispatched before this event.
     */
     deselectedNode: Node | null;
     /**
@@ -155,13 +157,17 @@ export interface TreeEvents {
    * is clicked again or passed to `selectNode` again with
    * `mustToggle: true`. No `tree.select` is dispatched for it.
    *
+   * When several nodes are selected and a click or `selectNode` selects just
+   * one node, it is dispatched for each node that loses the selection, except
+   * the one in the `deselectedNode` of `tree.select`.
+   *
    * ```js
    * element.addEventListener("tree.deselect", (e) => {
    *   console.log("deselected", e.detail.node.name);
    * });
    * ```
    *
-   * Selecting another node does not dispatch it — that is a `tree.select`
+   * Selecting another node does not dispatch it—that is a `tree.select`
    * with the previous node in `deselectedNode`. It is also not dispatched
    * by `selectNode` without `mustToggle: true`, `selectNode(null)`,
    * `removeFromSelection`, `removeNode`, `loadData` and restoring a saved
@@ -198,7 +204,7 @@ export interface TreeEvents {
   };
   /**
    * Dispatched when data is set on the tree, both from the `data` option
-   * and from a url.
+   * and from a URL.
    *
    * @group Loading data
    */
@@ -223,7 +229,7 @@ export interface TreeEvents {
   };
   /**
    * Dispatched when a request finishes. It is dispatched when the request
-   * fails too; a [`tree.load_failed`](#tree-load-failed) follows it.
+   * fails too, and a [`tree.load_failed`](#tree-load-failed) follows it.
    *
    * @group Loading data
    */

package/src/folderOpenState.ts

@@ -0,0 +1,38 @@
+import type { ClassNames } from "./classNames";
+
+import { getBoolString } from "./util";
+
+export interface FolderIcons {
+  closed?: globalThis.Node;
+  opened?: globalThis.Node;
+}
+
+/* The open state of a folder is shown on the toggler and on the <li>.
+ * These are used both when a folder is rendered and when it is opened or
+ * closed, so a rendered folder looks the same as a toggled one.
+ */
+
+export const setTogglerOpenState = (
+  toggler: HTMLElement,
+  isOpen: boolean,
+  classNames: ClassNames,
+  icons: FolderIcons,
+): void => {
+  toggler.classList.toggle(classNames.closed, !isOpen);
+  toggler.replaceChildren();
+
+  const iconElement = isOpen ? icons.opened : icons.closed;
+
+  if (iconElement) {
+    toggler.append(iconElement.cloneNode(true));
+  }
+};
+
+export const setFolderLiOpenState = (
+  li: HTMLElement,
+  isOpen: boolean,
+  classNames: ClassNames,
+): void => {
+  li.classList.toggle(classNames.closed, !isOpen);
+  li.setAttribute("aria-expanded", getBoolString(isOpen));
+};