wunderbaum 0.13.0 → 0.14.0

package/src/wb_node.ts

@@ -13,7 +13,6 @@ import {
   ApplyCommandType,
   ChangeType,
   CheckboxOption,
-  ColumnDefinition,
   ColumnEventInfoMap,
   ExpandAllOptions,
   IconOption,
@@ -37,7 +36,7 @@ import {
   SetStatusOptions,
   SortByPropertyOptions,
   SortCallback,
-  SortOrderType,
+  SortOptions,
   SourceType,
   TooltipOption,
   TristateType,
@@ -49,9 +48,11 @@ import {
   ICON_WIDTH,
   KEY_TO_NAVIGATION_MAP,
   makeNodeTitleMatcher,
+  NODE_TYPE_FOLDER,
   nodeTitleSorter,
   RESERVED_TREE_SOURCE_KEYS,
-  TEST_IMG,
+  TEST_FILE_PATH,
+  TEST_HTML,
   TITLE_SPAN_PAD_Y,
 } from "./common";
 import { Deferred } from "./deferred";
@@ -186,13 +187,13 @@ export class WunderbaumNode {
   _rowIdx: number | undefined = 0;
   _rowElem: HTMLDivElement | undefined = undefined;
 
-  constructor(tree: Wunderbaum, parent: WunderbaumNode, data: any) {
+  constructor(tree: Wunderbaum, parent: WunderbaumNode, data: WbNodeData) {
     util.assert(!parent || parent.tree === tree, `Invalid parent: ${parent}`);
     util.assert(!data.children, "'children' not allowed here");
 
     this.tree = tree;
     this.parent = parent;
-    this.key = "" + (data.key ?? ++WunderbaumNode.sequence);
+    this.key = tree._calculateKey(data, parent);
     this.title = "" + (data.title ?? "<" + this.key + ">");
     this.expanded = !!data.expanded;
     this.lazy = !!data.lazy;
@@ -332,12 +333,19 @@ export class WunderbaumNode {
         nodeData = [<WbNodeData>nodeData];
       }
       const forceExpand =
-        applyMinExpanLevel && _level < tree.options.minExpandLevel!;
+        applyMinExpanLevel && _level < tree.options.minExpandLevel;
       for (const child of <WbNodeData[]>nodeData) {
         const subChildren = child.children;
+        // Remove children property from source data because it should not be
+        // passed to the constructor of WunderbaumNode:
         delete child.children;
 
         const n = new WunderbaumNode(tree, this, child);
+
+        // Set `children` property again, so it can be used in `reload()`
+        if (subChildren != null) {
+          child.children = subChildren;
+        }
         if (forceExpand && !n.isUnloaded()) {
           n.expanded = true;
         }
@@ -804,7 +812,7 @@ export class WunderbaumNode {
     }
     return l;
   }
-  /** Return a string representing the hierachical node path, e.g. "a/b/c".
+  /** Return a string representing the hierarchical node path, e.g. "a/b/c".
    * @param includeSelf
    * @param part property name or callback
    * @param separator
@@ -814,10 +822,6 @@ export class WunderbaumNode {
     part: keyof WunderbaumNode | NodeAnyCallback = "title",
     separator: string = "/"
   ) {
-    // includeSelf = includeSelf !== false;
-    // part = part || "title";
-    // separator = separator || "/";
-
     let val;
     const path: string[] = [];
     const isFunc = typeof part === "function";
@@ -834,7 +838,7 @@ export class WunderbaumNode {
     return path.join(separator);
   }
 
-  /** Return the preceeding node (under the same parent) or null. */
+  /** Return the preceding node (under the same parent) or null. */
   getPrevSibling(): WunderbaumNode | null {
     const ac = this.parent.children!;
     const idx = ac.indexOf(this);
@@ -866,7 +870,7 @@ export class WunderbaumNode {
     return this.classes ? this.classes.has(className) : false;
   }
 
-  /** Return true if node ist the currently focused node. @since 0.9.0 */
+  /** Return true if node is the currently focused node. @since 0.9.0 */
   hasFocus(): boolean {
     return this.tree.focusNode === this;
   }
@@ -927,7 +931,7 @@ export class WunderbaumNode {
    * an expand operation is currently possible.
    */
   isExpandable(andCollapsed = false): boolean {
-    // `false` is never expandable (unoffical)
+    // `false` is never expandable (unofficial)
     if ((andCollapsed && this.expanded) || <any>this.children === false) {
       return false;
     }
@@ -1002,12 +1006,12 @@ export class WunderbaumNode {
     return !this.selected && !!this._partsel;
   }
 
-  /** Return true if this node has DOM representaion, i.e. is displayed in the viewport. */
+  /** Return true if this node has DOM representation, i.e. is displayed in the viewport. */
   isRadio(): boolean {
     return !!this.parent.radiogroup || this.getOption("checkbox") === "radio";
   }
 
-  /** Return true if this node has DOM representaion, i.e. is displayed in the viewport. */
+  /** Return true if this node has DOM representation, i.e. is displayed in the viewport. */
   isRendered(): boolean {
     return !!this._rowElem;
   }
@@ -1645,7 +1649,7 @@ export class WunderbaumNode {
   protected _render_markup(opts: RenderOptions) {
     const tree = this.tree;
     const treeOptions = tree.options;
-    const rowHeight = treeOptions.rowHeightPx!;
+    const rowHeight = treeOptions.rowHeightPx;
     const checkbox = this.getOption("checkbox");
     const columns = tree.columns;
     const level = this.getLevel();
@@ -1866,11 +1870,11 @@ export class WunderbaumNode {
     const rowDiv = this._rowElem!;
 
     // Row markup already exists
-    const nodeElem = rowDiv.querySelector("span.wb-node") as HTMLSpanElement;
-    const expanderSpan = nodeElem.querySelector(
+    const nodeSpan = rowDiv.querySelector("span.wb-node") as HTMLSpanElement;
+    const expanderElem = nodeSpan.querySelector(
       "i.wb-expander"
     ) as HTMLLIElement;
-    const checkboxSpan = nodeElem.querySelector(
+    const checkboxElem = nodeSpan.querySelector(
       "i.wb-checkbox"
     ) as HTMLLIElement;
 
@@ -1903,7 +1907,7 @@ export class WunderbaumNode {
       rowDiv.classList.add(...typeInfo.classes);
     }
 
-    if (expanderSpan) {
+    if (expanderElem) {
       let image = null;
       if (this._isLoading) {
         image = iconMap.loading;
@@ -1918,14 +1922,17 @@ export class WunderbaumNode {
       }
 
       if (image == null) {
-        expanderSpan.classList.add("wb-indent");
-      } else if (TEST_IMG.test(image)) {
-        expanderSpan.style.backgroundImage = `url('${image}')`;
+        expanderElem.className = "wb-expander";
+        expanderElem.classList.add("wb-indent");
+      } else if (TEST_HTML.test(image)) {
+        expanderElem.replaceWith(util.elemFromHtml(image));
+      } else if (TEST_FILE_PATH.test(image)) {
+        expanderElem.style.backgroundImage = `url('${image}')`;
       } else {
-        expanderSpan.className = "wb-expander " + image;
+        expanderElem.className = "wb-expander " + image;
       }
     }
-    if (checkboxSpan) {
+    if (checkboxElem) {
       let cbclass = "wb-checkbox ";
       if (this.isRadio()) {
         cbclass += "wb-radio ";
@@ -1945,7 +1952,7 @@ export class WunderbaumNode {
           cbclass += iconMap.checkUnchecked;
         }
       }
-      checkboxSpan.className = cbclass;
+      checkboxElem.className = cbclass;
     }
     // Fix active cell in cell-nav mode
     if (!opts.isNew) {
@@ -1955,9 +1962,9 @@ export class WunderbaumNode {
         colSpan.classList.remove("wb-error", "wb-invalid");
       }
       // Update icon (if not opts.isNew, which would rebuild markup anyway)
-      const iconSpan = nodeElem.querySelector("i.wb-icon") as HTMLElement;
+      const iconSpan = nodeSpan.querySelector("i.wb-icon") as HTMLElement;
       if (iconSpan) {
-        this._createIcon(nodeElem, iconSpan, !expanderSpan);
+        this._createIcon(nodeSpan, iconSpan, !expanderElem);
       }
     }
     // Adjust column width
@@ -2217,6 +2224,7 @@ export class WunderbaumNode {
   async setExpanded(flag: boolean = true, options?: SetExpandedOptions) {
     const { force, scrollIntoView, immediate, resetLazy } = options ?? {};
     const sendEvents = !options?.noEvents; // Default: send events
+
     if (
       !flag &&
       this.isExpanded() &&
@@ -2283,6 +2291,32 @@ export class WunderbaumNode {
   setKey(key: string | null, refKey: string | null) {
     throw new Error("Not yet implemented");
   }
+  // /**
+  //  * Calculate a *stable*, unique key for this node from its refKey (or title).
+  //  * We also add information from the parent, because a refKey may occur multiple
+  //  * times in a tree.
+  //  */
+  // calcUniqueKey() {
+  //   // Assuming that the parent's key was calculated the same way, we implicitly
+  //   // involve the whole refKey-path:
+  //   const s = this.key + (this.refKey || this.title);
+  //   // 32-bit has a high probability of collisions, so we pump up to 64-bit
+  //   // https://security.stackexchange.com/q/209882/207588
+  //   const h1 = util.murmurHash3(s, true);
+  //   return "id_" + h1 + util.murmurHash3(h1 + s, true);
+  //   // const l = [];
+  //   // // eslint-disable-next-line  @typescript-eslint/no-this-alias
+  //   // let node: WunderbaumNode = this;
+  //   // while (node.parent) {
+  //   //   l.unshift(node.refKey || node.key);
+  //   //   node = node.parent;
+  //   // }
+  //   // const path = l.join("/");
+  //   // 32-bit has a high probability of collisions, so we pump up to 64-bit
+  //   // https://security.stackexchange.com/q/209882/207588
+  //   // const h1 = util.murmurHash3(path, true);
+  //   // return "id_" + h1 + util.murmurHash3(h1 + path, true);
+  // }
 
   /**
    * Trigger a repaint, typically after a status or data change.
@@ -2320,6 +2354,24 @@ export class WunderbaumNode {
     return nodeList;
   }
 
+  /**
+   * Return an array of refKey values.
+   *
+   * RefKeys are unique identifiers for a node data, and are used to identify
+   * clones.
+   * If more than one node has the same refKey, it is only returned once.
+   * @param selected if true, only return refKeys of selected nodes.
+   */
+  getRefKeys(selected = false): string[] {
+    const refKeys = new Set<string>();
+    this.visit((node) => {
+      if (node.refKey != null && (!selected || node.selected)) {
+        refKeys.add(node.refKey);
+      }
+    });
+    return Array.from(refKeys);
+  }
+
   /** Toggle the check/uncheck state. */
   toggleSelected(options?: SetSelectedOptions): TristateType {
     let flag = this.isSelected();
@@ -2521,9 +2573,11 @@ export class WunderbaumNode {
         this.selected = flag;
         if (selectMode === "hier") {
           this.fixSelection3AfterClick();
-        } else if (selectMode === "single") {
+        } else if (selectMode === "single" && flag) {
           tree.visit((n) => {
-            n.selected = false;
+            if (n !== this) {
+              n.selected = false;
+            }
           });
         }
       }
@@ -2592,7 +2646,7 @@ export class WunderbaumNode {
           _setStatusNode({
             statusNodeType: status,
             title:
-              tree.options.strings!.loading +
+              tree.options.strings.loading +
               (message ? " (" + message + ")" : ""),
             checkbox: false,
             colspan: true,
@@ -2605,7 +2659,7 @@ export class WunderbaumNode {
         _setStatusNode({
           statusNodeType: status,
           title:
-            tree.options.strings!.loadError +
+            tree.options.strings.loadError +
             (message ? " (" + message + ")" : ""),
           checkbox: false,
           colspan: true,
@@ -2618,7 +2672,7 @@ export class WunderbaumNode {
       case "noData":
         _setStatusNode({
           statusNodeType: status,
-          title: message || tree.options.strings!.noData,
+          title: message || tree.options.strings.noData,
           checkbox: false,
           colspan: true,
           tooltip: details,
@@ -2646,35 +2700,19 @@ export class WunderbaumNode {
     this.update();
   }
 
-  _sortChildren(cmp: SortCallback, deep: boolean): void {
-    const cl = this.children;
-
-    if (!cl) {
-      return;
-    }
-    cl.sort(cmp);
-    if (deep) {
-      for (let i = 0, l = cl.length; i < l; i++) {
-        if (cl[i].children) {
-          cl[i]._sortChildren(cmp, deep);
-        }
-      }
-    }
-  }
-
   /**
    * Sort child list by title or custom criteria.
    * @param {function} cmp custom compare function(a, b) that returns -1, 0, or 1
    *    (defaults to sorting by title).
    * @param {boolean} deep pass true to sort all descendant nodes recursively
+   * @deprecated use {@link sort}
    */
   sortChildren(
     cmp: SortCallback | null = nodeTitleSorter,
     deep: boolean = false
   ): void {
-    this._sortChildren(cmp || nodeTitleSorter, deep);
-    this.tree.update(ChangeType.structure);
-    // this.triggerModify("sort"); // TODO
+    this.tree.logDeprecate("node.sortChildren()", { since: "0.14.0" });
+    return this.sort({ cmp: cmp ? cmp : undefined, deep: deep });
   }
 
   /**
@@ -2699,82 +2737,159 @@ export class WunderbaumNode {
   /**
    * Convenience method to implement column sorting.
    * @since 0.11.0
+   * @deprecated use {@link sort}
    */
   sortByProperty(options: SortByPropertyOptions) {
-    const {
-      caseInsensitive = true,
+    this.tree.logDeprecate("node.sortByProperty()", { since: "0.14.0" });
+    return this.sort(options);
+  }
+
+  /**
+   * Implement column sorting.
+   * @since 0.14.0
+   */
+  sort(options: SortOptions) {
+    const tree = this.tree;
+    let {
+      propName = undefined,
       deep = true,
-      nativeOrderPropName = "_nativeIndex",
+      key = undefined,
+      order = undefined,
+      caseInsensitive = true,
+      cmp = undefined,
+      // Support click on column sort header:
       updateColInfo = false,
+      nativeOrderPropName = "_nativeIndex",
+      colId = undefined,
     } = options;
 
-    let order: SortOrderType;
-    let colDef: ColumnDefinition | null;
+    propName ??= colId;
+    if (propName === "*") {
+      propName = "title";
+    }
+
+    const isFolder =
+      tree.options.sortFoldersFirst === true
+        ? (node: WunderbaumNode) =>
+            node.hasChildren() !== false || node.type === NODE_TYPE_FOLDER
+        : tree.options.sortFoldersFirst;
 
     if (updateColInfo) {
-      colDef = this.tree["_columnsById"][options.colId!];
+      const colDef = this.tree["_columnsById"][options.colId!];
       util.assert(colDef, `Invalid colId specified: ${options.colId}`);
-      order =
-        options.order ??
-        util.rotate(colDef!.sortOrder, ["asc", "desc", undefined]);
+      order ??= util.rotate(colDef.sortOrder, ["asc", "desc", undefined]);
 
       for (const col of this.tree.columns) {
         col.sortOrder = col === colDef ? order : undefined;
       }
-
+      if (order === undefined) {
+        propName = nativeOrderPropName;
+        order = "asc";
+      }
       this.tree.update(ChangeType.colStructure);
     } else {
-      order = options.order ?? "asc";
+      propName ??= "title";
+      order ??= "asc";
     }
 
-    let propName = options.propName ?? (options.colId || "");
-    if (propName === "*") {
-      propName = "title";
-    }
-    if (order == null) {
-      propName = nativeOrderPropName;
-      order = "asc";
-    }
-    this.logDebug(`sortByProperty(), propName=${propName}, ${order}`, options);
-    util.assert(propName, "No property name specified");
+    this.logDebug(`sort(), propName=${propName}, ${order}`, options);
+    util.assert(propName || cmp || key, "No `propName` or `key` specified");
 
-    const cmp = (a: WunderbaumNode, b: WunderbaumNode) => {
-      let av, bv;
-      if (NODE_DICT_PROPS.has(<string>propName)) {
-        av = a[propName as keyof WunderbaumNode];
-        bv = b[propName as keyof WunderbaumNode];
-      } else {
-        av = a.data[propName];
-        bv = b.data[propName];
-      }
-      if (av == null && bv == null) {
-        return 0;
-      }
-      if (av == null) {
-        av = typeof bv === "string" ? "" : 0;
-      } else if (typeof av === "boolean") {
-        av = av ? 1 : 0;
-      }
-      if (bv == null) {
-        bv = typeof av === "string" ? "" : 0;
-      } else if (typeof bv === "boolean") {
-        bv = bv ? 1 : 0;
+    // Define a key callback from the parameters we have
+    if (key == null && cmp == null) {
+      key = (node) => {
+        let val;
+        if (NODE_DICT_PROPS.has(<string>propName)) {
+          val = node[propName as keyof WunderbaumNode];
+        } else {
+          val = node.data[propName!];
+        }
+        if (caseInsensitive && typeof val === "string") {
+          val = val.toLowerCase();
+        }
+        return val;
+      };
+    }
+    // Define a compare callback that uses the key callback
+    if (cmp) {
+      util.assert(!key, "`key` and `cmp` are mutually exclusive");
+      tree.logDeprecate("SortOptions.cmp", {
+        since: "0.14.0",
+        hint: "use the `key` callback instead",
+      });
+    } else {
+      if (options.propName || options.caseInsensitive) {
+        tree.logWarn("sort(): ignoring propName, caseInsensitive");
       }
-      if (caseInsensitive) {
-        if (typeof av === "string") {
-          av = av.toLowerCase();
+
+      cmp = (a, b) => {
+        if (isFolder) {
+          const isFolderA = isFolder(a);
+          if (isFolderA !== isFolder(b)) {
+            return isFolderA ? -1 : 1;
+          }
+        }
+        let x = key!(a);
+        let y = key!(b);
+        // Assure we have reasonable comparisons with null values:
+        if (x == null) {
+          x = typeof y === "string" ? "" : 0;
+        } else if (typeof x === "boolean") {
+          x = x ? 1 : 0;
+        }
+        if (y == null) {
+          y = typeof x === "string" ? "" : 0;
+        } else if (typeof y === "boolean") {
+          y = y ? 1 : 0;
         }
-        if (typeof bv === "string") {
-          bv = bv.toLowerCase();
+
+        if (order === "desc") {
+          return x === y ? 0 : x > y ? -1 : 1;
         }
+        return x === y ? 0 : x > y ? 1 : -1;
+      };
+    }
+
+    function _sortChildren(cl: WunderbaumNode[]): void {
+      if (!cl) {
+        return;
       }
-      if (order === "desc") {
-        return av === bv ? 0 : av > bv ? -1 : 1;
+      cl.sort(cmp);
+      if (deep) {
+        for (let i = 0, l = cl.length; i < l; i++) {
+          if (cl[i].children) {
+            _sortChildren(cl[i].children!);
+          }
+        }
       }
-      return av === bv ? 0 : av > bv ? 1 : -1;
-    };
+    }
+    if (this.children) {
+      _sortChildren(this.children);
+    }
+    this.tree.update(ChangeType.structure);
+    // this.triggerModify("sort"); // TODO
+  }
 
-    return this.sortChildren(cmp, deep);
+  /**
+   * Re-apply current sorting if any (use after lazy load).
+   * Example:
+   * ```js
+   * load: function (e) {
+   *   // Whe loading a lazy branch, apply current sort order if any
+   *   e.node.resort();
+   * },
+   * ```
+   * @since 0.14.0
+   */
+  resort(options: SortOptions = {}): void {
+    for (const colDef of this.tree.columns) {
+      if (colDef.sortOrder) {
+        options.colId = colDef.id;
+        options.order = colDef.sortOrder;
+        this.sort(options);
+        break;
+      }
+    }
   }
 
   /**
@@ -2821,7 +2936,8 @@ export class WunderbaumNode {
    * @param {function} callback the callback function.
    *     Return false to stop iteration, return "skip" to skip this node and
    *     its children only.
-   * @see {@link IterableIterator<WunderbaumNode>}, {@link Wunderbaum.visit}.
+   * @see `wb_node.WunderbaumNode.IterableIterator<WunderbaumNode>`
+   * @see {@link Wunderbaum.visit}.
    */
   visit(
     callback: NodeVisitCallback,