tree-element 0.1.1 → 0.3.0

package/src/elementsRenderer.ts

@@ -6,362 +6,445 @@ import type { IconElement, OnCreateLi } from "./options";
 import { getBoolString } from "./util";
 
 interface ElementsRendererParams {
-    autoEscape: boolean;
-    buttonLeft: boolean;
-    classNames: ClassNames;
-    closedIcon?: IconElement;
-    dragAndDrop: boolean;
-    getTree: GetTree;
-    htmlElement: HTMLElement;
-    isNodeSelected: IsNodeSelected;
-    onCreateLi?: OnCreateLi;
-    openedIcon?: IconElement;
-    rtl?: boolean;
-    setNodeElement: (element: HTMLElement, node: Node) => void;
-    showEmptyFolder: boolean;
-    tabIndex?: number;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
+  autoEscape: boolean;
+  buttonLeft: boolean;
+  classNames: ClassNames;
+  closedIcon?: IconElement;
+  dragAndDrop: boolean;
+  getTree: GetTree;
+  htmlElement: HTMLElement;
+  isNodeSelected: IsNodeSelected;
+  onCreateLi?: OnCreateLi;
+  openedIcon?: IconElement;
+  rtl?: boolean;
+  setNodeElement: (element: HTMLElement, node: Node) => void;
+  showEmptyFolder: boolean;
+  tabIndex?: number;
 }
 
+/* Renders the tree to html.
+ *
+ * The children of a closed folder are not rendered. They are rendered when
+ * the folder is opened, see renderChildren.
+ *
+ * The elements are created by cloning templates. A template is a fully
+ * built <li> or <ul> with everything that is the same for every node
+ * (structure, roles, static classes, the toggler icon). Per node only the
+ * parts that differ are set: the title, the aria attributes and the
+ * selected and loading classes.
+ */
 export default class ElementsRenderer {
-    public closedIconElement?: HTMLElement | Text;
-    public openedIconElement?: HTMLElement | Text;
-    private autoEscape: boolean;
-    private buttonLeft: boolean;
-    private classNames: ClassNames;
-    private dragAndDrop: boolean;
-    private getTree: GetTree;
-    private htmlElement: HTMLElement;
-    private isNodeSelected: IsNodeSelected;
-    private onCreateLi?: OnCreateLi;
-    private rtl?: boolean;
-    private setNodeElement: (element: HTMLElement, node: Node) => void;
-    private showEmptyFolder: boolean;
-    private tabIndex?: number;
-
-    constructor({
-        autoEscape,
-        buttonLeft,
-        classNames,
-        closedIcon,
-        dragAndDrop,
-        getTree,
-        htmlElement,
-        isNodeSelected,
-        onCreateLi,
-        openedIcon,
-        rtl,
-        setNodeElement,
-        showEmptyFolder,
-        tabIndex,
-    }: ElementsRendererParams) {
-        this.autoEscape = autoEscape;
-        this.buttonLeft = buttonLeft;
-        this.classNames = classNames;
-        this.dragAndDrop = dragAndDrop;
-        this.getTree = getTree;
-        this.htmlElement = htmlElement;
-        this.isNodeSelected = isNodeSelected;
-        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 ?? "-");
+  public closedIconElement?: globalThis.Node;
+  public openedIconElement?: globalThis.Node;
+  private ariaLabel?: string;
+  private ariaLabelledBy?: string;
+  private autoEscape: boolean;
+  private buttonLeft: boolean;
+  private classNames: ClassNames;
+  private closedFolderTemplate: HTMLLIElement;
+  private dragAndDrop: boolean;
+  private getTree: GetTree;
+  private groupUlTemplate: HTMLUListElement;
+  private htmlElement: HTMLElement;
+  private isNodeSelected: IsNodeSelected;
+  private nodeTemplate: HTMLLIElement;
+  private onCreateLi?: OnCreateLi;
+  private openedFolderTemplate: HTMLLIElement;
+  private rootUlTemplate: HTMLUListElement;
+  private rtl?: boolean;
+  private setNodeElement: (element: HTMLElement, node: Node) => void;
+  private showEmptyFolder: boolean;
+  private tabIndex?: number;
+
+  constructor({
+    ariaLabel,
+    ariaLabelledBy,
+    autoEscape,
+    buttonLeft,
+    classNames,
+    closedIcon = "-",
+    dragAndDrop,
+    getTree,
+    htmlElement,
+    isNodeSelected,
+    onCreateLi,
+    openedIcon = "+",
+    rtl,
+    setNodeElement,
+    showEmptyFolder,
+    tabIndex,
+  }: ElementsRendererParams) {
+    this.ariaLabel = ariaLabel;
+    this.ariaLabelledBy = ariaLabelledBy;
+    this.autoEscape = autoEscape;
+    this.buttonLeft = buttonLeft;
+    this.classNames = classNames;
+    this.dragAndDrop = dragAndDrop;
+    this.getTree = getTree;
+    this.htmlElement = htmlElement;
+    this.isNodeSelected = isNodeSelected;
+    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);
+  }
+
+  public render(fromNode: Node | null): void {
+    if (fromNode?.parent) {
+      this.renderFromNode(fromNode);
+    } else {
+      this.renderFromRoot();
     }
+  }
+
+  /* Render the children of a rendered folder. Returns the new <ul>, or
+   * 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(
+          node.element,
+          node.children,
+          false,
+          node.getLevel() + 1,
+        );
+  }
 
-    public render(fromNode: Node | null): void {
-        if (fromNode?.parent) {
-            this.renderFromNode(fromNode);
-        } else {
-            this.renderFromRoot();
-        }
+  public renderFromNode(node: Node): void {
+    if (!node.element) {
+      return;
     }
 
-    public renderFromNode(node: Node): void {
-        if (!node.element) {
-            return;
-        }
-
-        const currentLi = node.element;
-        const newLi = this.createLi(node, node.getLevel());
-        currentLi.replaceWith(newLi);
+    const currentLi = node.element;
+    const newLi = this.createLi(node, node.getLevel());
+    currentLi.replaceWith(newLi);
 
-        // create children
-        this.createDomElements(newLi, node.children, false, node.getLevel() + 1);
+    if (this.mustRenderChildren(node)) {
+      this.createDomElements(newLi, node.children, false, node.getLevel() + 1);
     }
+  }
 
-    public renderFromRoot(): void {
-        this.htmlElement.textContent = '';
+  public renderFromRoot(): void {
+    this.htmlElement.textContent = "";
 
-        const tree = this.getTree();
+    const tree = this.getTree();
 
-        if (tree) {
-            this.createDomElements(this.htmlElement, tree.children, true, 1);
-        }
+    if (tree) {
+      this.createDomElements(this.htmlElement, tree.children, true, 1);
     }
-
-    private attachNodeData(node: Node, li: HTMLElement): void {
-        node.element = li;
-        this.setNodeElement(li, node);
+  }
+
+  private attachNodeData(node: Node, li: HTMLElement): void {
+    node.element = li;
+    this.setNodeElement(li, node);
+  }
+
+  /* Returns the template of a toggler icon; it is cloned for every folder.
+   * A string is parsed as html and becomes a fragment, so it can hold
+   * entities, text and elements.
+   */
+  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;
+    }
+    return value.nodeType ? value : undefined;
+  }
+
+  private createDomElements(
+    element: Element,
+    children: Node[],
+    isRootNode: boolean,
+    level: number,
+  ): HTMLUListElement {
+    const template = isRootNode ? this.rootUlTemplate : this.groupUlTemplate;
+    const ul = template.cloneNode() as HTMLUListElement;
+    element.append(ul);
+
+    for (const child of children) {
+      const li = this.createLi(child, level);
+      ul.append(li);
+
+      if (this.mustRenderChildren(child)) {
+        this.createDomElements(li, child.children, false, level + 1);
+      }
     }
 
-    private createButtonElement(
-        value: IconElement,
-    ): HTMLElement | Text | undefined {
-        if (typeof value === "string") {
-            // convert value to html
-            const div = document.createElement("div");
-            div.innerHTML = value;
-
-            return document.createTextNode(div.innerHTML);
-        } else if (value.nodeType) {
-            return value;
-        } else {
-            return undefined;
-        }
+    return ul;
+  }
+
+  private createFolderLi(
+    node: Node,
+    level: number,
+    isSelected: boolean,
+  ): HTMLLIElement {
+    const template = node.is_open
+      ? this.openedFolderTemplate
+      : this.closedFolderTemplate;
+    const li = template.cloneNode(true) as HTMLLIElement;
+
+    if (isSelected) {
+      li.classList.add(this.classNames.selected);
     }
 
-    private createDomElements(
-        element: Element,
-        children: Node[],
-        isRootNode: boolean,
-        level: number,
-    ): void {
-        const ul = this.createUl(isRootNode);
-        element.appendChild(ul);
-
-        for (const child of children) {
-            const li = this.createLi(child, level);
-            ul.appendChild(li);
-
-            if (child.hasChildren()) {
-                this.createDomElements(li, child.children, false, level + 1);
-            }
-        }
+    // li > div > [toggler], title span, [toggler]
+    const div = li.firstChild as HTMLDivElement;
+    const titleSpan = div.childNodes[
+      this.buttonLeft ? 1 : 0
+    ] as HTMLSpanElement;
+
+    this.fillTitleSpan(titleSpan, node.name, isSelected, level);
+
+    if (node.is_loading) {
+      li.classList.add(this.classNames.loading);
+      titleSpan.setAttribute("aria-busy", "true");
     }
 
-    private createFolderLi(
-        node: Node,
-        level: number,
-        isSelected: boolean,
-    ): HTMLLIElement {
-        const buttonClasses = this.getButtonClasses(node);
-        const folderClasses = this.getFolderClasses(node, isSelected);
-
-        const iconElement = node.is_open
-            ? this.openedIconElement
-            : this.closedIconElement;
-
-        // li
-        const li = document.createElement("li");
-        li.className = `${this.classNames.common} ${folderClasses}`;
-        li.setAttribute("role", "none");
-
-        // div
-        const div = document.createElement("div");
-        div.className = `${this.classNames.element} ${this.classNames.common}`;
-        div.setAttribute("role", "none");
-
-        li.appendChild(div);
-
-        // button link
-        const buttonLink = document.createElement("a");
-        buttonLink.className = buttonClasses;
-
-        if (iconElement) {
-            buttonLink.appendChild(iconElement.cloneNode(true));
-        }
-
-        if (this.buttonLeft) {
-            div.appendChild(buttonLink);
-        }
-
-        // title span
-        const titleSpan = this.createTitleSpan(
-            node.name,
-            isSelected,
-            true,
-            level,
-        );
-        titleSpan.setAttribute("aria-expanded", getBoolString(node.is_open));
-        div.appendChild(titleSpan);
+    return li;
+  }
 
-        if (!this.buttonLeft) {
-            div.appendChild(buttonLink);
-        }
+  /* Template for a folder <li>:
+   *   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.
+   */
+  private createFolderTemplate(isOpen: boolean): HTMLLIElement {
+    const liClasses = [this.classNames.common, this.classNames.folder];
 
-        return li;
+    if (!isOpen) {
+      liClasses.push(this.classNames.closed);
     }
 
-    /* Create the <li> element
-     * Attach it to node.element.
-     * Call onCreateLi
-     */
-    private createLi(node: Node, level: number): HTMLLIElement {
-        const isSelected = this.isNodeSelected(node);
+    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.setAttribute("aria-hidden", "true");
 
-        const mustShowFolder =
-            node.isFolder() || (node.isEmptyFolder && this.showEmptyFolder);
+    const iconElement = isOpen
+      ? this.openedIconElement
+      : this.closedIconElement;
 
-        const li = mustShowFolder
-            ? this.createFolderLi(node, level, isSelected)
-            : this.createNodeLi(node, level, isSelected);
+    if (iconElement) {
+      toggler.append(iconElement.cloneNode(true));
+    }
 
-        this.attachNodeData(node, li);
+    if (this.buttonLeft) {
+      div.append(toggler);
+    }
 
-        if (this.onCreateLi) {
-            this.onCreateLi(node, li, isSelected);
-        }
+    // title span
+    const titleSpan = this.createTitleSpanTemplate(true);
+    titleSpan.setAttribute("aria-expanded", getBoolString(isOpen));
+    div.append(titleSpan);
 
-        return li;
+    if (!this.buttonLeft) {
+      div.append(toggler);
     }
 
-    private createNodeLi(
-        node: Node,
-        level: number,
-        isSelected: boolean,
-    ): HTMLLIElement {
-        const liClasses = [this.classNames.common];
-
-        if (isSelected) {
-            liClasses.push(this.classNames.selected);
-        }
-
-        const classString = liClasses.join(" ");
-
-        // li
-        const li = document.createElement("li");
-        li.className = classString;
-        li.setAttribute("role", "none");
-
-        // div
-        const div = document.createElement("div");
-        div.className = `${this.classNames.element} ${this.classNames.common}`;
-        div.setAttribute("role", "none");
-
-        li.appendChild(div);
-
-        // title span
-        const titleSpan = this.createTitleSpan(
-            node.name,
-            isSelected,
-            false,
-            level,
-        );
-        div.appendChild(titleSpan);
+    return li;
+  }
+
+  /* Create the <li> element
+   * Attach it to node.element.
+   * Call onCreateLi
+   */
+  private createLi(node: Node, level: number): HTMLLIElement {
+    const isSelected = this.isNodeSelected(node);
 
-        return li;
+    const mustShowFolder =
+      node.isFolder() || (node.isEmptyFolder && this.showEmptyFolder);
+
+    const li = mustShowFolder
+      ? this.createFolderLi(node, level, isSelected)
+      : this.createNodeLi(node, level, isSelected);
+
+    this.attachNodeData(node, li);
+
+    if (this.onCreateLi) {
+      this.onCreateLi(node, li, isSelected);
     }
 
-    private createTitleSpan(
-        nodeName: string,
-        isSelected: boolean,
-        isFolder: boolean,
-        level: number,
-    ): HTMLSpanElement {
-        const titleSpan = document.createElement("span");
+    return li;
+  }
+
+  /*
+  Create the outer part of a <li> template: li > div
+  */
+  private createLiTemplate(liClasses: string): HTMLLIElement {
+    const li = document.createElement("li");
+    li.className = liClasses;
+    li.setAttribute("role", "none");
 
-        let classes = `${this.classNames.title} ${this.classNames.common}`;
+    const div = document.createElement("div");
+    div.className = `${this.classNames.element} ${this.classNames.common}`;
+    div.setAttribute("role", "none");
 
-        if (isFolder) {
-            classes += ` ${this.classNames.titleFolder}`;
-        }
+    li.append(div);
 
-        classes += ` ${this.buttonLeft ? this.classNames.titleButtonLeft : this.classNames.titleButtonRight}`;
+    return li;
+  }
 
-        titleSpan.className = classes;
+  private createNodeLi(
+    node: Node,
+    level: number,
+    isSelected: boolean,
+  ): HTMLLIElement {
+    const li = this.nodeTemplate.cloneNode(true) as HTMLLIElement;
 
-        if (isSelected) {
-            const tabIndex = this.tabIndex;
+    if (isSelected) {
+      li.classList.add(this.classNames.selected);
+    }
+
+    // li > div > title span
+    const div = li.firstChild as HTMLDivElement;
+    const titleSpan = div.firstChild as HTMLSpanElement;
+
+    this.fillTitleSpan(titleSpan, node.name, isSelected, level);
+
+    return li;
+  }
 
-            if (tabIndex !== undefined) {
-                titleSpan.setAttribute("tabindex", `${tabIndex}`);
-            }
-        }
+  /*
+  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;
 
-        this.setTreeItemAriaAttributes(titleSpan, nodeName, level, isSelected);
+    div.append(this.createTitleSpanTemplate(false));
 
-        if (this.autoEscape) {
-            titleSpan.textContent = nodeName;
-        } else {
-            titleSpan.innerHTML = nodeName;
-        }
+    return li;
+  }
 
-        return titleSpan;
+  private createTitleSpanTemplate(isFolder: boolean): HTMLSpanElement {
+    const titleSpan = document.createElement("span");
+
+    let classes = `${this.classNames.title} ${this.classNames.common}`;
+
+    if (isFolder) {
+      classes += ` ${this.classNames.titleFolder}`;
     }
 
-    private createUl(isRootNode: boolean): HTMLUListElement {
-        let classString;
-        let role;
+    classes += ` ${this.buttonLeft ? this.classNames.titleButtonLeft : this.classNames.titleButtonRight}`;
 
-        if (!isRootNode) {
-            classString = "";
-            role = "group";
-        } else {
-            classString = this.classNames.tree;
-            role = "tree";
+    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");
+    }
 
-            if (this.rtl) {
-                classString += ` ${this.classNames.rtl}`;
-            }
-        }
+    return titleSpan;
+  }
 
-        if (this.dragAndDrop) {
-            classString += ` ${this.classNames.dnd}`;
-        }
+  private createUlTemplate(isRootNode: boolean): HTMLUListElement {
+    let classString;
+    let role;
 
-        const ul = document.createElement("ul");
-        ul.className = `${this.classNames.common} ${classString}`;
+    if (isRootNode) {
+      classString = this.classNames.tree;
+      role = "tree";
 
-        ul.setAttribute("role", role);
+      if (this.rtl) {
+        classString += ` ${this.classNames.rtl}`;
+      }
+    } else {
+      classString = "";
+      role = "group";
+    }
 
-        return ul;
+    if (this.dragAndDrop) {
+      classString += ` ${this.classNames.dnd}`;
     }
 
-    private getButtonClasses(node: Node): string {
-        const classes = [this.classNames.toggler, this.classNames.common];
+    const ul = document.createElement("ul");
+    ul.className = `${this.classNames.common} ${classString}`;
 
-        if (!node.is_open) {
-            classes.push(this.classNames.closed);
-        }
+    ul.setAttribute("role", role);
 
-        if (this.buttonLeft) {
-            classes.push(this.classNames.togglerLeft);
-        } else {
-            classes.push(this.classNames.togglerRight);
-        }
+    if (isRootNode) {
+      if (this.ariaLabel !== undefined) {
+        ul.setAttribute("aria-label", this.ariaLabel);
+      }
 
-        return classes.join(" ");
+      if (this.ariaLabelledBy !== undefined) {
+        ul.setAttribute("aria-labelledby", this.ariaLabelledBy);
+      }
     }
 
-    private getFolderClasses(node: Node, isSelected: boolean): string {
-        const classes = [this.classNames.folder];
+    return ul;
+  }
+
+  /*
+  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-level", String(level));
+
+    if (isSelected) {
+      titleSpan.setAttribute("aria-selected", "true");
+
+      const tabIndex = this.tabIndex;
 
-        if (!node.is_open) {
-            classes.push(this.classNames.closed);
-        }
+      if (tabIndex !== undefined) {
+        titleSpan.setAttribute("tabindex", String(tabIndex));
+      }
+    }
 
-        if (isSelected) {
-            classes.push(this.classNames.selected);
-        }
+    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;
+    }
+  }
 
-        if (node.is_loading) {
-            classes.push(this.classNames.loading);
-        }
+  private getButtonClasses(isOpen: boolean): string {
+    const classes = [this.classNames.toggler, this.classNames.common];
 
-        return classes.join(" ");
+    if (!isOpen) {
+      classes.push(this.classNames.closed);
     }
 
-    private setTreeItemAriaAttributes(
-        element: HTMLElement,
-        name: string,
-        level: number,
-        isSelected: boolean,
-    ) {
-        element.setAttribute("aria-label", name);
-        element.setAttribute("aria-level", `${level}`);
-        element.setAttribute("aria-selected", getBoolString(isSelected));
-        element.setAttribute("role", "treeitem");
+    if (this.buttonLeft) {
+      classes.push(this.classNames.togglerLeft);
+    } else {
+      classes.push(this.classNames.togglerRight);
     }
+
+    return classes.join(" ");
+  }
+
+  /*
+  The children of a closed folder are rendered when it is opened
+  */
+  private mustRenderChildren(node: Node): boolean {
+    return node.hasChildren() && node.is_open === true;
+  }
 }