tree-element 0.1.0

package/src/elementsRenderer.ts

@@ -0,0 +1,367 @@
+import type { ClassNames } from "./classNames";
+import type { GetTree, IsNodeSelected } from "./methodTypes";
+import type { Node } from "./node";
+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;
+}
+
+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 render(fromNode: Node | null): void {
+        if (fromNode?.parent) {
+            this.renderFromNode(fromNode);
+        } else {
+            this.renderFromRoot();
+        }
+    }
+
+    public renderFromNode(node: Node): void {
+        if (!node.element) {
+            return;
+        }
+
+        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);
+    }
+
+    public renderFromRoot(): void {
+        this.htmlElement.textContent = '';
+
+        const tree = this.getTree();
+
+        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 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;
+        }
+    }
+
+    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);
+            }
+        }
+    }
+
+    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);
+
+        if (!this.buttonLeft) {
+            div.appendChild(buttonLink);
+        }
+
+        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);
+
+        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);
+        }
+
+        return li;
+    }
+
+    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;
+    }
+
+    private createTitleSpan(
+        nodeName: string,
+        isSelected: boolean,
+        isFolder: boolean,
+        level: number,
+    ): HTMLSpanElement {
+        const titleSpan = document.createElement("span");
+
+        let classes = `${this.classNames.title} ${this.classNames.common}`;
+
+        if (isFolder) {
+            classes += ` ${this.classNames.titleFolder}`;
+        }
+
+        classes += ` ${this.buttonLeft ? this.classNames.titleButtonLeft : this.classNames.titleButtonRight}`;
+
+        titleSpan.className = classes;
+
+        if (isSelected) {
+            const tabIndex = this.tabIndex;
+
+            if (tabIndex !== undefined) {
+                titleSpan.setAttribute("tabindex", `${tabIndex}`);
+            }
+        }
+
+        this.setTreeItemAriaAttributes(titleSpan, nodeName, level, isSelected);
+
+        if (this.autoEscape) {
+            titleSpan.textContent = nodeName;
+        } else {
+            titleSpan.innerHTML = nodeName;
+        }
+
+        return titleSpan;
+    }
+
+    private createUl(isRootNode: boolean): HTMLUListElement {
+        let classString;
+        let role;
+
+        if (!isRootNode) {
+            classString = "";
+            role = "group";
+        } else {
+            classString = this.classNames.tree;
+            role = "tree";
+
+            if (this.rtl) {
+                classString += ` ${this.classNames.rtl}`;
+            }
+        }
+
+        if (this.dragAndDrop) {
+            classString += ` ${this.classNames.dnd}`;
+        }
+
+        const ul = document.createElement("ul");
+        ul.className = `${this.classNames.common} ${classString}`;
+
+        ul.setAttribute("role", role);
+
+        return ul;
+    }
+
+    private getButtonClasses(node: Node): string {
+        const classes = [this.classNames.toggler, this.classNames.common];
+
+        if (!node.is_open) {
+            classes.push(this.classNames.closed);
+        }
+
+        if (this.buttonLeft) {
+            classes.push(this.classNames.togglerLeft);
+        } else {
+            classes.push(this.classNames.togglerRight);
+        }
+
+        return classes.join(" ");
+    }
+
+    private getFolderClasses(node: Node, isSelected: boolean): string {
+        const classes = [this.classNames.folder];
+
+        if (!node.is_open) {
+            classes.push(this.classNames.closed);
+        }
+
+        if (isSelected) {
+            classes.push(this.classNames.selected);
+        }
+
+        if (node.is_loading) {
+            classes.push(this.classNames.loading);
+        }
+
+        return classes.join(" ");
+    }
+
+    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");
+    }
+}

package/src/events.ts

@@ -0,0 +1,237 @@
+import type { Node, NodeData, Position } from "./node";
+
+export interface MoveInfo {
+    doMove: () => void;
+    movedNode: Node;
+    originalEvent: Event;
+    position: Position;
+    previousParent: Node | null;
+    targetNode: Node;
+}
+
+// The CustomEvent of a tree event, for example `TreeEvent<"tree.select">`.
+export type TreeEvent<Name extends TreeEventName = TreeEventName> = CustomEvent<
+    TreeEvents[Name]
+>;
+
+export type TreeEventName = keyof TreeEvents;
+
+// The events that the tree dispatches, and the type of their `detail`.
+// `undefined` means that the event has no `detail`.
+// The events reference in the docs is generated from this interface, so the
+// events are ordered chronologically instead of alphabetically.
+/* eslint-disable perfectionist/sort-interfaces */
+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:
+     *
+     * ```js
+     * element.addEventListener("tree.init", () => {
+     *   tree.selectNode(tree.getNodeByName("node1"));
+     * });
+     * ```
+     *
+     * No `detail`.
+     *
+     * With inline `data`, the tree is rendered inside the constructor, so
+     * this event has already fired by the time the constructor returns. Add
+     * the listener to the element _before_ creating the tree:
+     *
+     * ```js
+     * const element = document.getElementById("tree1");
+     *
+     * element.addEventListener("tree.init", () => {
+     *   // ...
+     * });
+     *
+     * const tree = new TreeElement({ data, htmlElement: element });
+     * ```
+     *
+     * @group Lifecycle
+     */
+    "tree.init": undefined;
+    /**
+     * Dispatched after the tree has been re-rendered. No `detail`.
+     *
+     * @group Lifecycle
+     */
+    "tree.refresh": undefined;
+    /**
+     * Dispatched when a node title is clicked. Call `preventDefault()` to
+     * stop the tree from selecting the node:
+     *
+     * ```js
+     * element.addEventListener("tree.click", (e) => {
+     *   e.preventDefault();
+     *   console.log("clicked", e.detail.node.name, "but not selected");
+     * });
+     * ```
+     *
+     * @group Mouse
+     */
+    "tree.click": {
+        node: Node;
+        originalEvent: MouseEvent;
+    };
+    /**
+     * Dispatched when a node title is double clicked.
+     *
+     * @group Mouse
+     */
+    "tree.dblclick": {
+        node: Node;
+        originalEvent: MouseEvent;
+    };
+    /**
+     * Dispatched on a right click on a node, unless `useContextMenu` is
+     * `false`. The browser's own menu is suppressed.
+     *
+     * @group Mouse
+     */
+    "tree.contextmenu": {
+        node: Node;
+        originalEvent: MouseEvent;
+    };
+    /**
+     * Dispatched when a folder is opened, after the animation.
+     *
+     * @group Opening and closing
+     */
+    "tree.open": {
+        node: Node;
+    };
+    /**
+     * Dispatched when a folder is closed, after the animation.
+     *
+     * @group Opening and closing
+     */
+    "tree.close": {
+        node: Node;
+    };
+    /**
+     * Dispatched when a node is selected. A deselection is
+     * [`tree.deselect`](#tree-deselect) instead, so `node` is always a node
+     * here.
+     *
+     * ```js
+     * element.addEventListener("tree.select", (e) => {
+     *   console.log("selected", e.detail.node.name);
+     * });
+     * ```
+     *
+     * @group Selection
+     */
+    "tree.select": {
+        /** The node that was selected before, if any. */
+        deselectedNode: Node | null;
+        /** 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.
+     *
+     * ```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`
+     * with the previous node in `deselectedNode`. It is also not dispatched
+     * with `mustToggle: false`, or by `selectNode(null)`,
+     * `removeFromSelection`, `removeNode`, `loadData` and restoring a saved
+     * state.
+     *
+     * @group Selection
+     */
+    "tree.deselect": {
+        node: Node;
+    };
+    /**
+     * Dispatched when a node is dropped after a drag.
+     *
+     * | `detail`                  | Type                              |
+     * | ------------------------- | --------------------------------- |
+     * | `moveInfo.movedNode`      | `Node`                            |
+     * | `moveInfo.targetNode`     | `Node`                            |
+     * | `moveInfo.position`       | `"before" \| "after" \| "inside"` |
+     * | `moveInfo.previousParent` | `Node \| null`                    |
+     * | `moveInfo.originalEvent`  | `Event`                           |
+     * | `moveInfo.doMove`         | `() => void`                      |
+     *
+     * Call `preventDefault()` to keep the tree as it is, and
+     * `moveInfo.doMove()` to apply the move later. See
+     * [Drag and drop](/guide/drag-and-drop#reacting-to-a-move).
+     *
+     * @group Drag and drop
+     */
+    "tree.move": {
+        /** @hidden The fields are in the table above. */
+        moveInfo: MoveInfo;
+    };
+    /**
+     * Dispatched when data is set on the tree, both from the `data` option
+     * and from a url.
+     *
+     * @group Loading data
+     */
+    "tree.set_data": {
+        /** The node whose children were replaced, if it was a subtree. */
+        node?: Node;
+        treeData?: NodeData[];
+    };
+    /**
+     * Dispatched when a request starts.
+     *
+     * @group Loading data
+     */
+    "tree.loading_data": {
+        element: HTMLElement;
+        /** The node whose children are loading, if it is a subtree. */
+        node?: Node;
+    };
+    /**
+     * Dispatched when a request finishes. It is dispatched when the request
+     * fails too; a [`tree.load_failed`](#tree-load-failed) follows it.
+     *
+     * @group Loading data
+     */
+    "tree.loaded_data": {
+        element: HTMLElement;
+        /** The node whose children were loaded, if it was a subtree. */
+        node?: Node;
+    };
+    /**
+     * Dispatched when a request returns an error status, after
+     * `tree.loaded_data`:
+     *
+     * ```js
+     * element.addEventListener("tree.load_failed", (e) => {
+     *   console.error("loading the tree failed", e.detail.response.status);
+     * });
+     * ```
+     *
+     * @group Loading data
+     */
+    "tree.load_failed": {
+        response: Response;
+    };
+}
+/* eslint-enable perfectionist/sort-interfaces */
+
+type TreeEventMap = {
+    [Name in TreeEventName]: TreeEvent<Name>;
+};
+
+// Type `addEventListener("tree.select", ...)` on elements, the document and the window.
+declare global {
+    interface DocumentEventMap extends TreeEventMap { }
+
+    interface HTMLElementEventMap extends TreeEventMap { }
+
+    interface WindowEventMap extends TreeEventMap { }
+}

package/src/header.txt

@@ -0,0 +1,16 @@
+Html-tree <%= version %>
+
+Copyright <%= year %> Marco Braak
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+@license