tree-element 0.2.0 → 0.3.1

package/src/elementsRenderer.ts

@@ -6,6 +6,8 @@ import type { IconElement, OnCreateLi } from "./options";
 import { getBoolString } from "./util";
 
 interface ElementsRendererParams {
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
   autoEscape: boolean;
   buttonLeft: boolean;
   classNames: ClassNames;
@@ -36,6 +38,8 @@ interface ElementsRendererParams {
 export default class ElementsRenderer {
   public closedIconElement?: globalThis.Node;
   public openedIconElement?: globalThis.Node;
+  private ariaLabel?: string;
+  private ariaLabelledBy?: string;
   private autoEscape: boolean;
   private buttonLeft: boolean;
   private classNames: ClassNames;
@@ -55,21 +59,25 @@ export default class ElementsRenderer {
   private tabIndex?: number;
 
   constructor({
+    ariaLabel,
+    ariaLabelledBy,
     autoEscape,
     buttonLeft,
     classNames,
-    closedIcon,
+    closedIcon = "-",
     dragAndDrop,
     getTree,
     htmlElement,
     isNodeSelected,
     onCreateLi,
-    openedIcon,
+    openedIcon = "+",
     rtl,
     setNodeElement,
     showEmptyFolder,
     tabIndex,
   }: ElementsRendererParams) {
+    this.ariaLabel = ariaLabel;
+    this.ariaLabelledBy = ariaLabelledBy;
     this.autoEscape = autoEscape;
     this.buttonLeft = buttonLeft;
     this.classNames = classNames;
@@ -82,8 +90,8 @@ export default class ElementsRenderer {
     this.setNodeElement = setNodeElement;
     this.showEmptyFolder = showEmptyFolder;
     this.tabIndex = tabIndex;
-    this.openedIconElement = this.createButtonElement(openedIcon ?? "+");
-    this.closedIconElement = this.createButtonElement(closedIcon ?? "-");
+    this.openedIconElement = this.createButtonElement(openedIcon);
+    this.closedIconElement = this.createButtonElement(closedIcon);
 
     this.rootUlTemplate = this.createUlTemplate(true);
     this.groupUlTemplate = this.createUlTemplate(false);
@@ -104,16 +112,14 @@ export default class ElementsRenderer {
    * null when the folder is not rendered or has no children.
    */
   public renderChildren(node: Node): HTMLUListElement | null {
-    if (!node.element || !node.hasChildren()) {
-      return null;
-    }
-
-    return this.createDomElements(
-      node.element,
-      node.children,
-      false,
-      node.getLevel() + 1,
-    );
+    return !node.element || !node.hasChildren()
+      ? null
+      : this.createDomElements(
+          node.element,
+          node.children,
+          false,
+          node.getLevel() + 1,
+        );
   }
 
   public renderFromNode(node: Node): void {
@@ -152,14 +158,12 @@ export default class ElementsRenderer {
   private createButtonElement(value: IconElement): globalThis.Node | undefined {
     if (typeof value === "string") {
       const template = document.createElement("template");
+      // eslint-disable-next-line no-unsanitized/property -- icon options are documented to accept html
       template.innerHTML = value;
 
       return template.content;
-    } else if (value.nodeType) {
-      return value;
-    } else {
-      return undefined;
     }
+    return value.nodeType ? value : undefined;
   }
 
   private createDomElements(
@@ -170,11 +174,11 @@ export default class ElementsRenderer {
   ): HTMLUListElement {
     const template = isRootNode ? this.rootUlTemplate : this.groupUlTemplate;
     const ul = template.cloneNode() as HTMLUListElement;
-    element.appendChild(ul);
+    element.append(ul);
 
     for (const child of children) {
       const li = this.createLi(child, level);
-      ul.appendChild(li);
+      ul.append(li);
 
       if (this.mustRenderChildren(child)) {
         this.createDomElements(li, child.children, false, level + 1);
@@ -198,11 +202,7 @@ export default class ElementsRenderer {
       li.classList.add(this.classNames.selected);
     }
 
-    if (node.is_loading) {
-      li.classList.add(this.classNames.loading);
-    }
-
-    // li > div > [button link], title span, [button link]
+    // li > div > [toggler], title span, [toggler]
     const div = li.firstChild as HTMLDivElement;
     const titleSpan = div.childNodes[
       this.buttonLeft ? 1 : 0
@@ -210,11 +210,16 @@ export default class ElementsRenderer {
 
     this.fillTitleSpan(titleSpan, node.name, isSelected, level);
 
+    if (node.is_loading) {
+      li.classList.add(this.classNames.loading);
+      titleSpan.setAttribute("aria-busy", "true");
+    }
+
     return li;
   }
 
   /* Template for a folder <li>:
-   *   li > div > [button link], title span, [button link]
+   *   li > div > [toggler], title span, [toggler]
    * The toggler icon and the aria-expanded attribute depend on the open
    * state, so there is a template for each.
    */
@@ -228,29 +233,31 @@ export default class ElementsRenderer {
     const li = this.createLiTemplate(liClasses.join(" "));
     const div = li.firstChild as HTMLDivElement;
 
-    // button link
-    const buttonLink = document.createElement("a");
-    buttonLink.className = this.getButtonClasses(isOpen);
+    // 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.setAttribute("aria-hidden", "true");
 
     const iconElement = isOpen
       ? this.openedIconElement
       : this.closedIconElement;
 
     if (iconElement) {
-      buttonLink.appendChild(iconElement.cloneNode(true));
+      toggler.append(iconElement.cloneNode(true));
     }
 
     if (this.buttonLeft) {
-      div.appendChild(buttonLink);
+      div.append(toggler);
     }
 
     // title span
     const titleSpan = this.createTitleSpanTemplate(true);
     titleSpan.setAttribute("aria-expanded", getBoolString(isOpen));
-    div.appendChild(titleSpan);
+    div.append(titleSpan);
 
     if (!this.buttonLeft) {
-      div.appendChild(buttonLink);
+      div.append(toggler);
     }
 
     return li;
@@ -279,7 +286,9 @@ export default class ElementsRenderer {
     return li;
   }
 
-  /* Create the outer part of a <li> template: li > div */
+  /*
+  Create the outer part of a <li> template: li > div
+  */
   private createLiTemplate(liClasses: string): HTMLLIElement {
     const li = document.createElement("li");
     li.className = liClasses;
@@ -289,7 +298,7 @@ export default class ElementsRenderer {
     div.className = `${this.classNames.element} ${this.classNames.common}`;
     div.setAttribute("role", "none");
 
-    li.appendChild(div);
+    li.append(div);
 
     return li;
   }
@@ -314,12 +323,14 @@ export default class ElementsRenderer {
     return li;
   }
 
-  /* Template for a <li> without children: li > div > title span */
+  /*
+  Template for a <li> without children: li > div > title span
+  */
   private createNodeTemplate(): HTMLLIElement {
     const li = this.createLiTemplate(this.classNames.common);
     const div = li.firstChild as HTMLDivElement;
 
-    div.appendChild(this.createTitleSpanTemplate(false));
+    div.append(this.createTitleSpanTemplate(false));
 
     return li;
   }
@@ -339,6 +350,11 @@ export default class ElementsRenderer {
     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;
   }
 
@@ -346,16 +362,16 @@ export default class ElementsRenderer {
     let classString;
     let role;
 
-    if (!isRootNode) {
-      classString = "";
-      role = "group";
-    } else {
+    if (isRootNode) {
       classString = this.classNames.tree;
       role = "tree";
 
       if (this.rtl) {
         classString += ` ${this.classNames.rtl}`;
       }
+    } else {
+      classString = "";
+      role = "group";
     }
 
     if (this.dragAndDrop) {
@@ -367,18 +383,29 @@ export default class ElementsRenderer {
 
     ul.setAttribute("role", role);
 
+    if (isRootNode) {
+      if (this.ariaLabel !== undefined) {
+        ul.setAttribute("aria-label", this.ariaLabel);
+      }
+
+      if (this.ariaLabelledBy !== undefined) {
+        ul.setAttribute("aria-labelledby", this.ariaLabelledBy);
+      }
+    }
+
     return ul;
   }
 
-  /* Set the parts of a cloned title span that differ per node */
+  /*
+  Set the parts of a cloned title span that differ per node
+  */
   private fillTitleSpan(
     titleSpan: HTMLSpanElement,
     nodeName: string,
     isSelected: boolean,
     level: number,
   ): void {
-    titleSpan.setAttribute("aria-label", nodeName);
-    titleSpan.setAttribute("aria-level", `${level}`);
+    titleSpan.setAttribute("aria-level", String(level));
 
     if (isSelected) {
       titleSpan.setAttribute("aria-selected", "true");
@@ -386,13 +413,14 @@ export default class ElementsRenderer {
       const tabIndex = this.tabIndex;
 
       if (tabIndex !== undefined) {
-        titleSpan.setAttribute("tabindex", `${tabIndex}`);
+        titleSpan.setAttribute("tabindex", String(tabIndex));
       }
     }
 
     if (this.autoEscape) {
       titleSpan.textContent = nodeName;
     } else {
+      // eslint-disable-next-line no-unsanitized/property -- the user opted out of escaping with autoEscape: false
       titleSpan.innerHTML = nodeName;
     }
   }
@@ -413,7 +441,9 @@ export default class ElementsRenderer {
     return classes.join(" ");
   }
 
-  /* The children of a closed folder are rendered when it is opened */
+  /*
+  The children of a closed folder are rendered when it is opened
+  */
   private mustRenderChildren(node: Node): boolean {
     return node.hasChildren() && node.is_open === true;
   }

package/src/events.ts

@@ -94,6 +94,23 @@ export interface TreeEvents {
     node: Node;
     originalEvent: MouseEvent;
   };
+  /**
+   * 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
+   * link would do, like opening the edit page of the node:
+   *
+   * ```js
+   * element.addEventListener("tree.activate", (e) => {
+   *   window.location.href = e.detail.node.url;
+   * });
+   * ```
+   *
+   * @group Keyboard
+   */
+  "tree.activate": {
+    node: Node;
+    originalEvent: KeyboardEvent;
+  };
   /**
    * Dispatched when a folder is opened, after the animation.
    *
@@ -124,15 +141,19 @@ export interface TreeEvents {
    * @group Selection
    */
   "tree.select": {
-    /** The node that was selected before, if any. */
+    /**
+    The node that was selected before, if any.
+    */
     deselectedNode: Node | null;
-    /** The node that is now selected. */
+    /**
+    The node that is now selected.
+    */
     node: Node;
   };
   /**
    * Dispatched when the selected node is deselected, which happens when it
-   * is clicked again or passed to `selectNode` again. No `tree.select` is
-   * dispatched for it.
+   * is clicked again or passed to `selectNode` again with
+   * `mustToggle: true`. No `tree.select` is dispatched for it.
    *
    * ```js
    * element.addEventListener("tree.deselect", (e) => {
@@ -142,7 +163,7 @@ export interface TreeEvents {
    *
    * Selecting another node does not dispatch it — that is a `tree.select`
    * with the previous node in `deselectedNode`. It is also not dispatched
-   * with `mustToggle: false`, or by `selectNode(null)`,
+   * by `selectNode` without `mustToggle: true`, `selectNode(null)`,
    * `removeFromSelection`, `removeNode`, `loadData` and restoring a saved
    * state.
    *
@@ -170,7 +191,9 @@ export interface TreeEvents {
    * @group Drag and drop
    */
   "tree.move": {
-    /** @hidden The fields are in the table above. */
+    /**
+    @hidden The fields are in the table above.
+    */
     moveInfo: MoveInfo;
   };
   /**
@@ -180,7 +203,9 @@ export interface TreeEvents {
    * @group Loading data
    */
   "tree.set_data": {
-    /** The node whose children were replaced, if it was a subtree. */
+    /**
+    The node whose children were replaced, if it was a subtree.
+    */
     node?: Node;
     treeData?: NodeData[];
   };
@@ -191,7 +216,9 @@ export interface TreeEvents {
    */
   "tree.loading_data": {
     element: HTMLElement;
-    /** The node whose children are loading, if it is a subtree. */
+    /**
+    The node whose children are loading, if it is a subtree.
+    */
     node?: Node;
   };
   /**
@@ -202,7 +229,9 @@ export interface TreeEvents {
    */
   "tree.loaded_data": {
     element: HTMLElement;
-    /** The node whose children were loaded, if it was a subtree. */
+    /**
+    The node whose children were loaded, if it was a subtree.
+    */
     node?: Node;
   };
   /**
@@ -222,9 +251,13 @@ export interface TreeEvents {
    * @group Loading data
    */
   "tree.load_failed": {
-    /** The error thrown by `fetch`, if the request failed with a network error. */
+    /**
+    The error thrown by `fetch`, if the request failed with a network error.
+    */
     error?: unknown;
-    /** The response, if the request returned an error status. */
+    /**
+    The response, if the request returned an error status.
+    */
     response?: Response;
   };
 }