tree-element 0.1.0

package/src/nodeElement/borderDropHint.ts

@@ -0,0 +1,37 @@
+import type { ClassNames } from "../classNames";
+import type { DropHint } from "../dragAndDropHandler/types";
+
+class BorderDropHint implements DropHint {
+    private hint?: HTMLElement;
+
+    constructor(
+        element: HTMLElement,
+        scrollLeft: number,
+        classNames: ClassNames,
+    ) {
+        const div = element.querySelector(`:scope > .${classNames.element}`);
+
+        if (!div) {
+            this.hint = undefined;
+            return;
+        }
+
+        const width = Math.max(element.offsetWidth + scrollLeft - 4, 0);
+        const height = Math.max(element.clientHeight - 4, 0);
+
+        const hint = document.createElement("span");
+        hint.className = classNames.border;
+        hint.style.width = `${width}px`;
+        hint.style.height = `${height}px`;
+
+        this.hint = hint;
+
+        div.append(this.hint);
+    }
+
+    public remove(): void {
+        this.hint?.remove();
+    }
+}
+
+export default BorderDropHint;

package/src/nodeElement/folderElement.ts

@@ -0,0 +1,140 @@
+import type { AnimationSpeed } from "../animation";
+import type { TriggerEvent } from "../methodTypes";
+import type { Position } from "../node";
+import type { NodeElementParams } from "./index";
+
+import { slideDown, slideUp } from "../animation";
+import NodeElement from "./index";
+
+interface FolderElementParams extends NodeElementParams {
+    closedIconElement?: HTMLElement | Text;
+    openedIconElement?: HTMLElement | Text;
+    triggerEvent: TriggerEvent;
+}
+
+class FolderElement extends NodeElement {
+    private closedIconElement?: HTMLElement | Text;
+    private openedIconElement?: HTMLElement | Text;
+    private triggerEvent: TriggerEvent;
+
+    constructor({
+        classNames,
+        closedIconElement,
+        getScrollLeft,
+        node,
+        openedIconElement,
+        tabIndex,
+        treeElement,
+        triggerEvent,
+    }: FolderElementParams) {
+        super({
+            classNames,
+            getScrollLeft,
+            node,
+            tabIndex,
+            treeElement,
+        });
+
+        this.closedIconElement = closedIconElement;
+        this.openedIconElement = openedIconElement;
+        this.triggerEvent = triggerEvent;
+    }
+
+    public close(slide: boolean, animationSpeed: AnimationSpeed): void {
+        if (!this.node.is_open) {
+            return;
+        }
+
+        this.node.is_open = false;
+
+        const button = this.getButton();
+        button.classList.add(this.classNames.closed);
+        button.innerHTML = "";
+
+        const closedIconElement = this.closedIconElement;
+
+        if (closedIconElement) {
+            const icon = closedIconElement.cloneNode(true);
+            button.appendChild(icon);
+        }
+
+        const doClose = (): void => {
+            this.element.classList.add(this.classNames.closed);
+
+            const titleSpan = this.getTitleSpan();
+            titleSpan.setAttribute("aria-expanded", "false");
+
+            this.triggerEvent("tree.close", {
+                node: this.node,
+            });
+        };
+
+        const ul = this.getUl();
+
+        if (slide) {
+            slideUp(ul, animationSpeed, doClose);
+        } else {
+            ul.style.display = "none";
+            doClose();
+        }
+    }
+
+    public async open(
+        slide: boolean,
+        animationSpeed: AnimationSpeed,
+    ): Promise<void> {
+        return new Promise(resolve => {
+            if (this.node.is_open) {
+                resolve();
+                return;
+            }
+
+            this.node.is_open = true;
+
+            const button = this.getButton();
+            button.classList.remove(this.classNames.closed);
+            button.innerHTML = "";
+
+            const openedIconElement = this.openedIconElement;
+
+            if (openedIconElement) {
+                const icon = openedIconElement.cloneNode(true);
+                button.appendChild(icon);
+            }
+
+            const doOpen = (): void => {
+                this.element.classList.remove(this.classNames.closed);
+
+                const titleSpan = this.getTitleSpan();
+                titleSpan.setAttribute("aria-expanded", "true");
+
+                this.triggerEvent("tree.open", {
+                    node: this.node,
+                });
+
+                resolve();
+            };
+
+            const ul = this.getUl();
+
+            if (slide) {
+                slideDown(ul, animationSpeed, doOpen);
+            } else {
+                ul.style.display = "block";
+                doOpen();
+            }
+        });
+    }
+
+    protected mustShowBorderDropHint(position: Position): boolean {
+        return !this.node.is_open && position === "inside";
+    }
+
+    private getButton(): HTMLLinkElement {
+        return this.element.querySelector(
+            `:scope > .${this.classNames.element} > a.${this.classNames.toggler}`,
+        ) as HTMLLinkElement;
+    }
+}
+
+export default FolderElement;

package/src/nodeElement/ghostDropHint.ts

@@ -0,0 +1,84 @@
+import type { ClassNames } from "../classNames";
+import type { DropHint } from "../dragAndDropHandler/types";
+import type { Node, Position } from "../node";
+
+class GhostDropHint implements DropHint {
+    private classNames: ClassNames;
+    private element: HTMLElement;
+    private ghost: HTMLElement;
+    private node: Node;
+
+    constructor(
+        node: Node,
+        element: HTMLElement,
+        position: Position,
+        classNames: ClassNames,
+    ) {
+        this.classNames = classNames;
+        this.element = element;
+        this.node = node;
+        this.ghost = this.createGhostElement();
+
+        switch (position) {
+            case "after":
+                this.moveAfter();
+                break;
+
+            case "before":
+                this.moveBefore();
+                break;
+
+            case "inside": {
+                if (node.isFolder() && node.is_open) {
+                    this.moveInsideOpenFolder();
+                } else {
+                    this.moveInside();
+                }
+            }
+        }
+    }
+
+    public remove(): void {
+        this.ghost.remove();
+    }
+
+    private createGhostElement() {
+        const { circle, common, ghost: ghostClass, line } = this.classNames;
+
+        const ghost = document.createElement("li");
+        ghost.className = `${common} ${ghostClass}`;
+
+        const circleSpan = document.createElement("span");
+        circleSpan.className = `${common} ${circle}`;
+        ghost.append(circleSpan);
+
+        const lineSpan = document.createElement("span");
+        lineSpan.className = `${common} ${line}`;
+        ghost.append(lineSpan);
+
+        return ghost;
+    }
+
+    private moveAfter(): void {
+        this.element.after(this.ghost);
+    }
+
+    private moveBefore(): void {
+        this.element.before(this.ghost);
+    }
+
+    private moveInside(): void {
+        this.element.after(this.ghost);
+        this.ghost.classList.add(this.classNames.inside);
+    }
+
+    private moveInsideOpenFolder(): void {
+        const childElement = this.node.children[0]?.element;
+
+        if (childElement) {
+            childElement.before(this.ghost);
+        }
+    }
+}
+
+export default GhostDropHint;

package/src/nodeElement/index.ts

@@ -0,0 +1,103 @@
+import type { ClassNames } from "../classNames";
+import type { DropHint } from "../dragAndDropHandler/types";
+import type { GetScrollLeft } from "../methodTypes";
+import type { Node, Position } from "../node";
+
+import BorderDropHint from "./borderDropHint";
+import GhostDropHint from "./ghostDropHint";
+
+export interface NodeElementParams {
+    classNames: ClassNames;
+    getScrollLeft: GetScrollLeft;
+    node: Node;
+    tabIndex?: number;
+    treeElement: HTMLElement;
+}
+
+class NodeElement {
+    public element: HTMLElement;
+    public node: Node;
+    protected classNames: ClassNames;
+    private getScrollLeft: GetScrollLeft;
+    private tabIndex?: number;
+    private treeElement: HTMLElement;
+
+    constructor({
+        classNames,
+        getScrollLeft,
+        node,
+        tabIndex,
+        treeElement,
+    }: NodeElementParams) {
+        this.classNames = classNames;
+        this.getScrollLeft = getScrollLeft;
+        this.node = node;
+        this.tabIndex = tabIndex;
+        this.treeElement = treeElement;
+
+        node.element ??= this.treeElement;
+        this.element = node.element;
+
+    }
+
+    public addDropHint(position: Position): DropHint {
+        if (this.mustShowBorderDropHint(position)) {
+            return new BorderDropHint(
+                this.element,
+                this.getScrollLeft(),
+                this.classNames,
+            );
+        } else {
+            return new GhostDropHint(
+                this.node,
+                this.element,
+                position,
+                this.classNames,
+            );
+        }
+    }
+
+    public deselect(): void {
+        this.element.classList.remove(this.classNames.selected);
+
+        const titleSpan = this.getTitleSpan();
+        titleSpan.removeAttribute("tabindex");
+        titleSpan.setAttribute("aria-selected", "false");
+
+        titleSpan.blur();
+    }
+
+    public select(mustSetFocus: boolean): void {
+        this.element.classList.add(this.classNames.selected);
+
+        const titleSpan = this.getTitleSpan();
+        const tabIndex = this.tabIndex;
+
+        // Check for null or undefined
+        if (tabIndex != null) {
+            titleSpan.setAttribute("tabindex", tabIndex.toString());
+        }
+
+        titleSpan.setAttribute("aria-selected", "true");
+
+        if (mustSetFocus) {
+            titleSpan.focus();
+        }
+    }
+
+    protected getTitleSpan(): HTMLSpanElement {
+        return this.element.querySelector(
+            `:scope > .${this.classNames.element} > span.${this.classNames.title}`,
+        ) as HTMLSpanElement;
+    }
+
+    protected getUl(): HTMLUListElement {
+        return this.element.querySelector(":scope > ul") as HTMLUListElement;
+    }
+
+    protected mustShowBorderDropHint(position: Position): boolean {
+        return position === "inside";
+    }
+}
+
+export default NodeElement;

package/src/nodeUtils.ts

@@ -0,0 +1,12 @@
+import type { NodeData, NodeRecord } from "./node";
+
+interface NodeRecordWithChildren extends NodeRecord {
+    children: NodeData[];
+}
+
+export const isNodeRecordWithChildren = (
+    data: NodeData,
+): data is NodeRecordWithChildren =>
+    typeof data === "object" &&
+    "children" in data &&
+    data.children instanceof Array;

package/src/options.ts

@@ -0,0 +1,325 @@
+import type { AnimationSpeed } from "./animation";
+import type { Node, NodeData } from "./node";
+
+export type DataFilter = (data: unknown) => NodeData[];
+
+export type DataUrl = DataUrlFunction | string;
+
+export type DragMethod = (node: Node, event: Event | Touch) => void;
+
+export type IconElement = HTMLElement | string;
+
+export type OnCanMove = ((node: Node) => boolean) | undefined;
+
+export type OnCanMoveTo = (
+  node: Node,
+  targetNode: Node,
+  positionName: string,
+) => boolean;
+
+export type OnCanSelectNode = (node: Node) => boolean
+
+export type OnCreateLi = (node: Node, el: HTMLElement, isSelected: boolean) => void;
+
+export type OnGetStateFromStorage = (() => string) | undefined;
+
+export type OnIsMoveHandle = (el: HTMLElement) => boolean;
+
+export type OnSetStateFromStorage = ((data: string) => void) | undefined;
+
+export interface TreeElementOptions {
+  /**
+   * The duration of the slide animation: `"fast"` is 200ms, `"slow"` is
+   * 600ms, a number is milliseconds.
+   *
+   * @defaultValue `"fast"`
+   * @group Appearance
+   */
+  animationSpeed: AnimationSpeed;
+  /**
+   * Escape node names. With `false`, names are inserted as html — only do
+   * that for data you control.
+   *
+   * @defaultValue `true`
+   * @group Data
+   */
+  autoEscape: boolean;
+  /**
+   * Which levels are open initially: `false` none, `true` all, a number that
+   * many levels starting at `0` (so `0` opens the top level, `1` the first
+   * two levels).
+   *
+   * @defaultValue `false`
+   * @group Appearance
+   */
+  autoOpen: boolean | number;
+  /**
+   * Put the open/close button before the node title. With `false` it goes
+   * after it.
+   *
+   * @defaultValue `true`
+   * @group Appearance
+   */
+  buttonLeft: boolean;
+  /**
+   * The prefix of the css classes the widget puts on the elements it
+   * creates: with `"my-tree"` a title gets `my-tree-title` instead of
+   * `tree-element-title`. The bundled stylesheet uses the default prefix, so
+   * change it only if you bring your own css. See
+   * [Styling](/guide/styling#changing-the-class-names).
+   *
+   * @defaultValue `"tree-element"`
+   * @group Appearance
+   */
+  classPrefix: string;
+  /**
+   * The icon of a closed folder. A string is inserted as html; an element is
+   * cloned for every node.
+   *
+   * Type: `HTMLElement | string`
+   *
+   * @defaultValue `"►"` (`►`), or `"◀"` (`◀`) when `rtl` is
+   * true.
+   * @group Appearance
+   */
+  closedIcon?: IconElement;
+  /**
+   * The class that every element of the widget gets.
+   *
+   * @defaultValue `"<classPrefix>-common"`
+   * @group Appearance
+   */
+  commonClassName?: string;
+  /**
+   * The nodes of the tree. See [Data](/guide/data) for the format.
+   *
+   * @group Data
+   */
+  data?: NodeData[];
+  /**
+   * Transforms a response from `dataUrl` into node data. Use it when the
+   * server wraps the nodes in another object.
+   *
+   * Type: `(data: unknown) => NodeData[]`
+   *
+   * @group Data
+   */
+  dataFilter?: DataFilter;
+  /**
+   * A url to fetch the data from, or a function that returns one. The
+   * function is called with the node that is being loaded, and without an
+   * argument for the initial load. See
+   * [Loading on demand](/guide/loading-on-demand).
+   *
+   * Type: `string | ((node?: Node) => string)`
+   *
+   * @defaultValue The element's `data-url` attribute.
+   * @group Data
+   */
+  dataUrl?: DataUrl;
+  /**
+   * Let the user move nodes by dragging them.
+   *
+   * @defaultValue `false`
+   * @group Drag and drop
+   */
+  dragAndDrop: boolean;
+  /**
+   * Handle the arrow keys when the focus is on the tree. See
+   * [Selection](/guide/selection#keyboard-navigation).
+   *
+   * @defaultValue `true`
+   * @group Selection
+   */
+  keyboardSupport: boolean;
+  /**
+   * The class used to create nodes. Subclass [`Node`](/reference/node) to
+   * add your own methods. The `Node` class is not exposed on the global
+   * `TreeElement`, so this option needs the `lib` build.
+   *
+   * @example
+   * ```js
+   * import TreeElement from "tree-element/lib/index.js";
+   * import { Node } from "tree-element/lib/node.js";
+   *
+   * class MyNode extends Node {
+   *   fullName() {
+   *     return this.getParent()
+   *       ? `${this.getParent().name}/${this.name}`
+   *       : this.name;
+   *   }
+   * }
+   *
+   * new TreeElement({ data, htmlElement, nodeClass: MyNode });
+   * ```
+   *
+   * @defaultValue `Node`
+   * @group Advanced
+   */
+  nodeClass: typeof Node;
+  /**
+   * Called before a drag starts. Return `false` to keep the node in place.
+   *
+   * Type: `(node: Node) => boolean`
+   *
+   * @group Drag and drop
+   */
+  onCanMove?: OnCanMove;
+  /**
+   * Called for a possible drop. `position` is `"before"`, `"after"` or
+   * `"inside"`. Return `false` to refuse the drop.
+   *
+   * Type: `(movedNode: Node, targetNode: Node, position: string) => boolean`
+   *
+   * @group Drag and drop
+   */
+  onCanMoveTo?: OnCanMoveTo;
+  /**
+   * Called before a node is selected. Return `false` to refuse.
+   *
+   * Type: `(node: Node) => boolean`
+   *
+   * @group Selection
+   */
+  onCanSelectNode?: OnCanSelectNode;
+  /**
+   * Called after the `li` of a node is created, so you can add to it. See
+   * [Styling](/guide/styling#customizing-the-markup).
+   *
+   * Type: `(node: Node, li: HTMLElement, isSelected: boolean) => void`
+   *
+   * @group Appearance
+   */
+  onCreateLi?: OnCreateLi;
+  /**
+   * Called while a node is being dragged.
+   *
+   * Type: `(node: Node, event: Event | Touch) => void`
+   *
+   * @group Drag and drop
+   */
+  onDragMove?: DragMethod;
+  /**
+   * Called when a drag ends.
+   *
+   * Type: `(node: Node, event: Event | Touch) => void`
+   *
+   * @group Drag and drop
+   */
+  onDragStop?: DragMethod;
+  /**
+   * Read the saved state, as a json string, from somewhere other than
+   * `localStorage`.
+   *
+   * Type: `() => string`
+   *
+   * @group State
+   */
+  onGetStateFromStorage?: OnGetStateFromStorage;
+  /**
+   * Decides whether an element inside a node starts a drag. Without it, the
+   * whole node is a handle.
+   *
+   * Type: `(element: HTMLElement) => boolean`
+   *
+   * @group Drag and drop
+   */
+  onIsMoveHandle?: OnIsMoveHandle;
+  /**
+   * Write the state, as a json string, to somewhere other than
+   * `localStorage`.
+   *
+   * Type: `(state: string) => void`
+   *
+   * @group State
+   */
+  onSetStateFromStorage?: OnSetStateFromStorage;
+  /**
+   * The icon of an open folder.
+   *
+   * Type: `HTMLElement | string`
+   *
+   * @defaultValue `"&#x25bc;"` (`▼`)
+   * @group Appearance
+   */
+  openedIcon?: IconElement;
+  /**
+   * How long, in milliseconds, a closed folder has to be hovered during a
+   * drag before it opens. `false` never opens folders while dragging.
+   *
+   * @defaultValue `500`
+   * @group Drag and drop
+   */
+  openFolderDelay: false | number;
+  /**
+   * Mirror the tree for right-to-left languages.
+   *
+   * @defaultValue The element's `data-rtl` attribute, otherwise `false`.
+   * @group Appearance
+   */
+  rtl?: boolean;
+  /**
+   * Remember the open and selected nodes in `localStorage`. A string is used
+   * as the storage key; `true` uses `tree`. See
+   * [Saving state](/guide/saving-state).
+   *
+   * @defaultValue `false`
+   * @group State
+   */
+  saveState: boolean | string;
+  /**
+   * Allow the user to select nodes.
+   *
+   * @defaultValue `true`
+   * @group Selection
+   */
+  selectable: boolean;
+  /**
+   * Render a node with `children: []` as a folder instead of as a leaf.
+   *
+   * @defaultValue `false`
+   * @group Appearance
+   */
+  showEmptyFolder: boolean;
+  /**
+   * Animate opening and closing folders.
+   *
+   * @defaultValue `true`
+   * @group Appearance
+   */
+  slide: boolean;
+  /**
+   * How long, in milliseconds, the mouse has to be held down on a node
+   * before a drag starts.
+   *
+   * @defaultValue `300`
+   * @group Drag and drop
+   */
+  startDndDelay?: number;
+  /**
+   * The `tabindex` of the selected node's title, which is what makes the
+   * tree focusable.
+   *
+   * @defaultValue `0`
+   * @group Selection
+   */
+  tabIndex?: number;
+  /**
+   * The class of the root `ul`.
+   *
+   * @defaultValue The value of `classPrefix`.
+   * @group Appearance
+   */
+  treeClassName?: string;
+  /**
+   * Handle right clicks on a node: the browser menu is suppressed and
+   * [`tree.contextmenu`](/reference/events#tree-contextmenu) is dispatched
+   * instead.
+   *
+   * @defaultValue `true`
+   * @group Selection
+   */
+  useContextMenu: boolean;
+}
+
+type DataUrlFunction = (node?: Node) => string;