wunderbaum 0.13.0 → 0.14.1

package/src/wunderbaum.ts

@@ -25,11 +25,6 @@ import {
   ApplyCommandType,
   ChangeType,
   ColumnDefinitionList,
-  DynamicBoolOption,
-  DynamicCheckboxOption,
-  DynamicIconOption,
-  DynamicStringOption,
-  DynamicTooltipOption,
   ExpandAllOptions,
   FilterModeType,
   FilterNodesOptions,
@@ -51,7 +46,6 @@ import {
   SetColumnOptions,
   SetStateOptions,
   SetStatusOptions,
-  SortByPropertyOptions,
   SortCallback,
   SourceType,
   TreeStateDefinition,
@@ -59,20 +53,29 @@ import {
   VisitRowsOptions,
   WbEventInfo,
   WbNodeData,
+  FilterOptionsType,
+  EditOptionsType,
+  DndOptionsType,
+  SortOptions,
+  DeprecationOptions,
+  SortByPropertyOptions,
+  ReloadOptions,
+  LoadLazyNodesOptions,
 } from "./types";
 import {
   DEFAULT_DEBUGLEVEL,
-  iconMaps,
+  defaultIconMaps,
   makeNodeTitleStartMatcher,
   nodeTitleSorter,
   RENDER_MAX_PREFETCH,
   DEFAULT_ROW_HEIGHT,
-  TEST_IMG,
+  TEST_FILE_PATH,
+  TEST_HTML,
 } from "./common";
 import { WunderbaumNode } from "./wb_node";
 import { Deferred } from "./deferred";
 import { EditExtension } from "./wb_ext_edit";
-import { WunderbaumOptions } from "./wb_options";
+import { InitWunderbaumOptions, WunderbaumOptions } from "./wb_options";
 import { DebouncedFunction } from "./debounce";
 
 class WbSystemRoot extends WunderbaumNode {
@@ -116,7 +119,7 @@ export class Wunderbaum {
 
   protected readonly _updateViewportThrottled: DebouncedFunction<() => void>;
   protected extensionList: WunderbaumExtension<any>[] = [];
-  protected extensions: ExtensionsDict = {};
+  protected extensions: ExtensionsDict = <ExtensionsDict>{};
 
   /** Merged options from constructor args and tree- and extension defaults. */
   public options: WunderbaumOptions;
@@ -129,6 +132,7 @@ export class Wunderbaum {
 
   protected _activeNode: WunderbaumNode | null = null;
   protected _focusNode: WunderbaumNode | null = null;
+  protected _initialSource: SourceType | null = null;
 
   /** Currently active node if any.
    * Use {@link WunderbaumNode.setActive|setActive} to modify.
@@ -148,18 +152,7 @@ export class Wunderbaum {
   /** Shared properties, referenced by `node.type`. */
   public types: NodeTypeDefinitionMap = {};
   /** List of column definitions. */
-  public columns: ColumnDefinitionList = []; // any[] = [];
-  /** Show/hide a checkbox or radiobutton. */
-  public checkbox?: DynamicCheckboxOption;
-  /** Show/hide a node icon. */
-  public icon?: DynamicIconOption;
-  /** Show/hide a tooltip for the node icon. */
-  public iconTooltip?: DynamicStringOption;
-  /** Show/hide a tooltip. */
-  public tooltip?: DynamicTooltipOption;
-  /** Define a node checkbox as readonly. */
-  public unselectable?: DynamicBoolOption;
-
+  public columns: ColumnDefinitionList = [];
   protected _columnsById: { [key: string]: any } = {};
   protected resizeObserver: ResizeObserver;
 
@@ -170,11 +163,22 @@ export class Wunderbaum {
   public readonly ready: Promise<any>;
   /** Expose some useful methods of the util.ts module as `Wunderbaum.util`. */
   public static util = util;
+  /** A map of default iconMaps.
+   * May be used as default, when passing partial icon definition maps:
+   * ```js
+   * const tree = new mar10.Wunderbaum({
+   *   ...
+   *   iconMap: Object.assign(Wunderbaum.iconMaps.bootstrap, {
+   *     folder: "bi bi-archive",
+   *   }),
+   * });
+   * ```
+   */
+  public static iconMaps = defaultIconMaps;
   /** Expose some useful methods of the util.ts module as `tree._util`. */
   public _util = util;
 
   // --- SELECT ---
-  // /** @internal */
   // public selectRangeAnchor: WunderbaumNode | null = null;
 
   // --- BREADCRUMB ---
@@ -198,39 +202,50 @@ export class Wunderbaum {
   // --- EDIT ---
   protected lastClickTime = 0;
 
-  constructor(options: WunderbaumOptions) {
-    const opts = (this.options = util.extend(
+  constructor(options: InitWunderbaumOptions) {
+    // Set default options and merge with user options
+    const initOptions = Object.assign<
+      InitWunderbaumOptions,
+      InitWunderbaumOptions
+    >(
       {
-        id: null,
-        source: null, // URL for GET/PUT, Ajax options, or callback
-        element: null, // <div class="wunderbaum">
+        id: undefined,
+        source: [], // URL for GET/PUT, Ajax options, or callback
+        element: util.unsafeCast<string>(null),
         debugLevel: DEFAULT_DEBUGLEVEL, // 0:quiet, 1:errors, 2:warnings, 3:info, 4:verbose
         header: null, // Show/hide header (pass bool or string)
-        // headerHeightPx: ROW_HEIGHT,
         rowHeightPx: DEFAULT_ROW_HEIGHT,
         iconMap: "bootstrap",
-        columns: null,
-        types: null,
-        // escapeTitles: true,
+        columns: [], //util.unsafeCast<ColumnDefinitionList>(null),
+        types: {},
         enabled: true,
         fixedCol: false,
         showSpinner: false,
         checkbox: false,
         minExpandLevel: 0,
         emptyChildListExpandable: false,
-        // updateThrottleWait: 200,
         skeleton: false,
+        autoCollapse: false,
+        adjustHeight: true,
         connectTopBreadcrumb: null,
+        columnsFilterable: false,
+        columnsMenu: false,
+        columnsResizable: false,
+        columnsSortable: false,
         selectMode: "multi", // SelectModeType
+        scrollIntoViewOnExpandClick: true,
+        // --- Extensions (actually set by exensions on init)
+        dnd: util.unsafeCast<DndOptionsType>(null),
+        edit: util.unsafeCast<EditOptionsType>(null),
+        filter: util.unsafeCast<FilterOptionsType>(null),
         // --- KeyNav ---
-        navigationModeOption: null, // NavModeEnum,
+        navigationModeOption: util.unsafeCast<NavModeEnum>(null),
         quicksearch: true,
         // --- Events ---
-        iconBadge: null,
-        change: null,
-        // enhanceTitle: null,
-        error: null,
-        receive: null,
+        // iconBadge: null,
+        // change: null,
+        // ...
+
         // --- Strings ---
         strings: {
           loadError: "Error",
@@ -243,7 +258,9 @@ export class Wunderbaum {
         },
       },
       options
-    ));
+    );
+    const opts = initOptions as WunderbaumOptions;
+    this.options = opts;
 
     const readyDeferred = new Deferred();
     this.ready = readyDeferred.promise();
@@ -270,7 +287,8 @@ export class Wunderbaum {
         }
       });
 
-    this.id = opts.id || "wb_" + ++Wunderbaum.sequence;
+    this.id = initOptions.id || "wb_" + ++Wunderbaum.sequence;
+    delete initOptions.id;
     this.root = new WbSystemRoot(this);
 
     this._registerExtension(new KeynavExtension(this));
@@ -286,21 +304,25 @@ export class Wunderbaum {
     );
 
     // --- Evaluate options
-    this.columns = opts.columns;
-    delete opts.columns;
+    this.columns = initOptions.columns || [];
+    delete initOptions.columns;
     if (!this.columns || !this.columns.length) {
       const title = typeof opts.header === "string" ? opts.header : this.id;
       this.columns = [{ id: "*", title: title, width: "*" }];
     }
 
-    if (opts.types) {
-      this.setTypes(opts.types, true);
+    if (initOptions.types) {
+      this.setTypes(initOptions.types, true);
     }
-    delete opts.types;
+    delete initOptions.types;
 
     // --- Create Markup
-    this.element = util.elemFromSelector<HTMLDivElement>(opts.element)!;
-    util.assert(!!this.element, `Invalid 'element' option: ${opts.element}`);
+    this.element = util.elemFromSelector<HTMLDivElement>(initOptions.element)!;
+    util.assert(
+      !!this.element,
+      `Invalid 'element' option: ${initOptions.element}`
+    );
+    delete (<any>initOptions).element;
 
     this.element.classList.add("wunderbaum");
     if (!this.element.getAttribute("tabindex")) {
@@ -403,17 +425,17 @@ export class Wunderbaum {
 
     // --- apply initial options
     ["enabled", "fixedCol"].forEach((optName) => {
-      if (opts[optName] != null) {
-        this.setOption(optName, opts[optName]);
+      if ((opts as any)[optName] != null) {
+        this.setOption(optName, (opts as any)[optName]);
       }
     });
 
     // --- Load initial data
-    if (opts.source) {
+    if (initOptions.source) {
       if (opts.showSpinner) {
         this.nodeListElement.innerHTML = `<progress class='spinner'>${opts.strings.loading}</progress>`;
       }
-      this.load(opts.source)
+      this.load(initOptions.source)
         .then(() => {
           // The source may have defined columns, so we may adjust the nav mode
           if (opts.navigationModeOption == null) {
@@ -444,16 +466,20 @@ export class Wunderbaum {
     this.update(ChangeType.any);
 
     // --- Bind listeners
-    this.element.addEventListener("scroll", (e: Event) => {
-      // this.log(`scroll, scrollTop:${e.target.scrollTop}`, e);
-      this.update(ChangeType.scroll);
-    });
+    this._registerEventHandlers();
 
     this.resizeObserver = new ResizeObserver((entries) => {
       // this.log("ResizeObserver: Size changed", entries);
       this.update(ChangeType.resize);
     });
     this.resizeObserver.observe(this.element);
+  }
+
+  private _registerEventHandlers() {
+    this.element.addEventListener("scroll", (e: Event) => {
+      // this.log(`scroll, scrollTop:${e.target.scrollTop}`, e);
+      this.update(ChangeType.scroll);
+    });
 
     util.onEvent(this.element, "click", ".wb-button,.wb-col-icon", (e) => {
       const info = Wunderbaum.getEventInfo(e);
@@ -473,10 +499,6 @@ export class Wunderbaum {
 
       // this.log("click", info);
 
-      // if (this._selectRange(info) === false) {
-      //   return;
-      // }
-
       if (
         this._callEvent("click", { event: e, node: node, info: info }) === false
       ) {
@@ -500,18 +522,18 @@ export class Wunderbaum {
           node.startEditTitle();
         }
 
-        if (info.colIdx >= 0) {
-          node.setActive(true, { colIdx: info.colIdx, event: e });
-        } else {
-          node.setActive(true, { event: e });
-        }
-
         if (info.region === NodeRegion.expander) {
           node.setExpanded(!node.isExpanded(), {
-            scrollIntoView: options.scrollIntoViewOnExpandClick !== false,
+            scrollIntoView: this.options.scrollIntoViewOnExpandClick !== false,
           });
         } else if (info.region === NodeRegion.checkbox) {
           node.toggleSelected();
+        } else {
+          if (info.colIdx >= 0) {
+            node.setActive(true, { colIdx: info.colIdx, event: e });
+          } else {
+            node.setActive(true, { event: e });
+          }
         }
       }
       this.lastClickTime = Date.now();
@@ -559,7 +581,7 @@ export class Wunderbaum {
       this._callEvent("focus", { flag: flag, event: e });
 
       if (flag && this.isRowNav() && !this.isEditingTitle()) {
-        if ((opts.navigationModeOption as NavModeEnum) === NavModeEnum.row) {
+        if (this.options.navigationModeOption === NavModeEnum.row) {
           targetNode?.setActive();
         } else {
           this.setCellNav();
@@ -573,7 +595,6 @@ export class Wunderbaum {
       }
     });
   }
-
   /**
    * Return a Wunderbaum instance, from element, id, index, or event.
    *
@@ -627,14 +648,16 @@ export class Wunderbaum {
 
   /**
    * Return the icon-function -> icon-definition mapping.
+   * @deprecated Use {@link Wunderbaum.iconMaps}
    */
   get iconMap(): IconMapType {
-    const map = this.options.iconMap!;
+    const map = this.options.iconMap;
     if (typeof map === "string") {
-      return iconMaps[map];
+      return defaultIconMaps[map as keyof typeof defaultIconMaps];
     }
     return map;
   }
+
   /**
    * Return a WunderbaumNode instance from element or event.
    */
@@ -687,7 +710,42 @@ export class Wunderbaum {
     }
   }
 
-  /** Add node to tree's bookkeeping data structures. */
+  /**
+   * Calculate a *stable*, unique key for a node from its refKey (or title).
+   * We also add information from the parent, because a refKey may occur multiple
+   * times in a tree (but not as child of the same parent).
+   * @internal
+   */
+  _calculateKey(data: WbNodeData, parent?: WunderbaumNode): string {
+    if (data.key) {
+      // Always use an explicitly passed key
+      return data.key;
+    }
+    // Auto-keys are optional, use a monotonic counter by default:
+    if (!this.options.autoKeys) {
+      return "" + ++WunderbaumNode.sequence;
+    }
+    // Add the parent's key to the hash. Assuming this was generated by the
+    // same algorithm, this should incorporate the whole path:
+    const s = (parent ? parent.key : "") + (data.refKey || data.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);
+    let key = "id_" + h1 + util.murmurHash3(h1 + s, true);
+    // Check for collisions
+    // (Most likely if the same title occurs multiple in the same parent).
+    const existingNode = this.keyMap.get(key);
+    if (existingNode) {
+      key += "." + ++Wunderbaum.sequence;
+      this.logWarn(
+        `Node with existing key: '${existingNode}', using ${key}.`,
+        data
+      );
+    }
+    return key;
+  }
+
+  /** Add node to tree's bookkeeping data structures. @internal */
   _registerNode(node: WunderbaumNode): void {
     const key = node.key;
     util.assert(key != null, `Missing key: '${node}'.`);
@@ -704,7 +762,7 @@ export class Wunderbaum {
     }
   }
 
-  /** Remove node from tree's bookkeeping data structures. */
+  /** Remove node from tree's bookkeeping data structures. @internal  */
   _unregisterNode(node: WunderbaumNode): void {
     // Remove refKey reference from map (if any)
     const rk = node.refKey;
@@ -807,7 +865,7 @@ export class Wunderbaum {
    * pixel is visible.
    */
   getTopmostVpNode(complete = true) {
-    const rowHeight = this.options.rowHeightPx!;
+    const rowHeight = this.options.rowHeightPx;
     const gracePx = 1; // ignore subpixel scrolling
     const scrollParent = this.element;
     // const headerHeight = this.headerElement.clientHeight;  // May be 0
@@ -824,7 +882,7 @@ export class Wunderbaum {
 
   /** Return the lowest visible node in the viewport. */
   getLowestVpNode(complete = true) {
-    const rowHeight = this.options.rowHeightPx!;
+    const rowHeight = this.options.rowHeightPx;
     const scrollParent = this.element;
     const headerHeight = this.headerElement.clientHeight; // May be 0
     const scrollTop = scrollParent.scrollTop;
@@ -840,6 +898,20 @@ export class Wunderbaum {
     return this._getNodeByRowIdx(bottomIdx)!;
   }
 
+  /** Return preceding visible node in the viewport. */
+  protected _getPrevNodeInView(node?: WunderbaumNode, ofs = 1) {
+    this.visitRows(
+      (n) => {
+        node = n;
+        if (ofs-- <= 0) {
+          return false;
+        }
+      },
+      { reverse: true, start: node || this.getActiveNode() }
+    );
+    return node;
+  }
+
   /** Return following visible node in the viewport. */
   protected _getNextNodeInView(
     node?: WunderbaumNode,
@@ -1138,24 +1210,40 @@ export class Wunderbaum {
   /** Run code, but defer rendering of viewport until done.
    *
    * ```js
-   * tree.runWithDeferredUpdate(() => {
-   *   return someFuncThatWouldUpdateManyNodes();
+   * const res = tree.runWithDeferredUpdate(() => {
+   *   return someFunctionThatWouldUpdateManyNodes();
    * });
    * ```
    */
-  runWithDeferredUpdate(func: () => any, hint = null): any {
+  runWithDeferredUpdate<T>(func: () => util.NotPromise<T>): T {
     try {
       this.enableUpdate(false);
       const res = func();
       util.assert(
         !(res instanceof Promise),
-        `Promise return not allowed: ${res}`
+        `Promise return not allowed (see 'runWithDeferredUpdateAsync()'): ${res}`
       );
       return res;
     } finally {
       this.enableUpdate(true);
     }
   }
+  /** Run code, but defer rendering of viewport until done.
+   *
+   * ```js
+   * const res = await tree.runWithDeferredUpdate(async () => {
+   *   return someAsyncFunctionThatWouldUpdateManyNodes();
+   * });
+   * ```
+   */
+  async runWithDeferredUpdateAsync<T>(func: () => Promise<T>): Promise<T> {
+    try {
+      this.enableUpdate(false);
+      return await func();
+    } finally {
+      this.enableUpdate(true);
+    }
+  }
 
   /** Recursively expand all expandable nodes (triggers lazy load if needed). */
   async expandAll(flag: boolean = true, options?: ExpandAllOptions) {
@@ -1180,6 +1268,18 @@ export class Wunderbaum {
     return this.root.getSelectedNodes(stopOnParents);
   }
 
+  /**
+   * 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[] {
+    return this.root.getRefKeys(selected);
+  }
+
   /*
    * Return an array of selected nodes.
    */
@@ -1348,7 +1448,7 @@ export class Wunderbaum {
     where: NavigationType,
     includeHidden = false
   ) {
-    const rowHeight = this.options.rowHeightPx!;
+    const rowHeight = this.options.rowHeightPx;
     let res = null;
     const pageSize = Math.floor(
       this.listContainerElement.clientHeight / rowHeight
@@ -1495,6 +1595,20 @@ export class Wunderbaum {
     return this.root.format(name_cb, connectors);
   }
 
+  /**
+   * Always returns null (so a tree instance behaves as `tree.root`).
+   */
+  get parent(): null {
+    return null;
+  }
+
+  /**
+   * Return a list of top-level nodes.
+   */
+  get children(): WunderbaumNode[] {
+    return this.root.children || [];
+  }
+
   /**
    * Return the active cell (`span.wb-col`) of the currently active node or null.
    */
@@ -1617,7 +1731,7 @@ export class Wunderbaum {
 
   /** Return true if any node title or grid cell is currently beeing edited.
    *
-   * See also {@link Wunderbaum.isEditingTitle}.
+   * See also {@link isEditingTitle}.
    */
   isEditing(): boolean {
     const focusElem = this.nodeListElement.querySelector(
@@ -1628,7 +1742,7 @@ export class Wunderbaum {
 
   /** Return true if any node is currently in edit-title mode.
    *
-   * See also {@link WunderbaumNode.isEditingTitle} and {@link Wunderbaum.isEditing}.
+   * See also {@link WunderbaumNode.isEditingTitle} and {@link isEditing}.
    */
   isEditingTitle(): boolean {
     return this._callMethod("edit.isEditingTitle");
@@ -1651,7 +1765,7 @@ export class Wunderbaum {
   }
 
   /** Write to `console.log` with tree name as prefix if opts.debugLevel >= 4.
-   * @see {@link Wunderbaum.logDebug}
+   * @see {@link logDebug}
    */
   log(...args: any[]) {
     if (this.options.debugLevel! >= 4) {
@@ -1661,7 +1775,7 @@ export class Wunderbaum {
 
   /** Write to `console.debug`  with tree name as prefix if opts.debugLevel >= 4.
    * and browser console level includes debug/verbose messages.
-   * @see {@link Wunderbaum.log}
+   * @see {@link log}
    */
   logDebug(...args: any[]) {
     if (this.options.debugLevel! >= 4) {
@@ -1705,6 +1819,20 @@ export class Wunderbaum {
     }
   }
 
+  /** Emit a warning for deprecated methods. @internal */
+  logDeprecate(method: string, options?: DeprecationOptions) {
+    if (this.options.debugLevel! >= 2) {
+      let msg = `${this}: ${method} is deprecated`;
+      if (options?.since) {
+        msg += ` since ${options.since}`;
+      }
+      if (options?.hint) {
+        msg += ` (${options.since})`;
+      }
+      console.warn(msg + "."); // eslint-disable-line no-console
+    }
+  }
+
   /** Reset column widths to default. @since 0.10.0 */
   resetColumns() {
     this.columns.forEach((col) => {
@@ -1739,7 +1867,7 @@ export class Wunderbaum {
     }
     util.assert(node && node._rowIdx != null, `Invalid node: ${node}`);
 
-    const rowHeight = this.options.rowHeightPx!;
+    const rowHeight = this.options.rowHeightPx;
     const scrollParent = this.element;
     const headerHeight = this.headerElement.clientHeight; // May be 0
     const scrollTop = scrollParent.scrollTop;
@@ -1895,47 +2023,69 @@ export class Wunderbaum {
   }
 
   /** Return the current selection/expansion/activation status. @experimental */
-  getState(options: GetStateOptions): TreeStateDefinition {
-    let expandedKeys = undefined;
-    if (options.expandedKeys !== false) {
-      expandedKeys = [];
+  getState(options: GetStateOptions = {}): TreeStateDefinition {
+    const {
+      activeKey = true,
+      expandedKeys = false,
+      selectedKeys = false,
+    } = options;
+
+    const expandSet = new Set<string>();
+
+    if (expandedKeys) {
       for (const node of this) {
-        if (node.expanded) {
-          expandedKeys.push(node.key);
+        if (node.isExpanded() && node.hasChildren()) {
+          expandSet.add(node.key);
         }
       }
     }
+    // Parents of active node are always expanded
+    if (activeKey && this.activeNode) {
+      this.activeNode.visitParents((n) => {
+        if (n.parent) {
+          expandSet.add(n.key);
+        }
+      }, false);
+    }
 
     const state: TreeStateDefinition = {
+      expandedKeys: expandSet.size ? Array.from(expandSet) : undefined,
       activeKey: this.activeNode?.key ?? null,
       activeColIdx: this.activeColIdx,
-      selectedKeys:
-        options.selectedKeys === false
-          ? undefined
-          : this.getSelectedNodes().flatMap((n) => n.key),
-      expandedKeys: expandedKeys,
+      selectedKeys: selectedKeys
+        ? this.getSelectedNodes().flatMap((n) => n.key)
+        : undefined,
     };
     return state;
   }
 
   /** Apply selection/expansion/activation status. @experimental */
-  setState(state: TreeStateDefinition, options: SetStateOptions) {
-    this.runWithDeferredUpdate(() => {
+  async setState(state: TreeStateDefinition, options: SetStateOptions = {}) {
+    const { expandLazy = true } = options;
+    return this.runWithDeferredUpdateAsync(async () => {
+      if (state.expandedKeys && state.expandedKeys.length) {
+        if (expandLazy) {
+          // Expand all keys recursively, even if they are not in the tree yet
+          await this._loadLazyNodes(state.expandedKeys, {
+            expand: true,
+            noEvents: true,
+          });
+        } else {
+          for (const key of state.expandedKeys) {
+            this.findKey(key)?.setExpanded(true);
+          }
+        }
+      }
+      if (state.activeKey) {
+        this.setActiveNode(state.activeKey);
+      }
       if (state.selectedKeys) {
         this.selectAll(false);
         for (const key of state.selectedKeys) {
           this.findKey(key)?.setSelected(true);
         }
       }
-      if (state.expandedKeys) {
-        for (const key of state.expandedKeys) {
-          this.findKey(key)?.setExpanded(true);
-        }
-      }
-      if (state.activeKey) {
-        this.setActiveNode(state.activeKey);
-      }
-      if (state.activeColIdx != null) {
+      if (this.isCellNav() && state.activeColIdx != null) {
         this.setColumn(state.activeColIdx);
       }
     });
@@ -2136,23 +2286,39 @@ export class Wunderbaum {
    * @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.root.sortChildren(cmp, deep);
+    this.logDeprecate("sortChildren()", { since: "0.14.0" });
+    return this.sort({
+      cmp: cmp ? cmp : undefined,
+      deep: deep,
+      propName: "title",
+    });
   }
 
   /**
    * Convenience method to implement column sorting.
    * @see {@link WunderbaumNode.sortByProperty}.
    * @since 0.11.0
+   * @deprecated use {@link sort}
    */
   sortByProperty(options: SortByPropertyOptions) {
+    this.logDeprecate("sortByProperty()", { since: "0.14.0" });
     this.root.sortByProperty(options);
   }
 
+  /**
+   * Sort nodes list by title or custom criteria.
+   * @since 0.14.0
+   */
+  sort(options: SortOptions): void {
+    this.root.sort(options);
+  }
+
   /** Convert tree to an array of plain objects.
    *
    * @param callback is called for every node, in order to allow
@@ -2419,11 +2585,9 @@ export class Wunderbaum {
     if (!icon) {
       iconElem = document.createElement("i");
       iconElem.className = "wb-icon";
-    } else if (icon.indexOf("<") >= 0) {
-      // HTML
+    } else if (TEST_HTML.test(icon)) {
       iconElem = util.elemFromHtml(icon);
-    } else if (TEST_IMG.test(icon)) {
-      // Image URL
+    } else if (TEST_FILE_PATH.test(icon)) {
       iconElem = util.elemFromHtml(
         `<i class="wb-icon" style="background-image: url('${icon}');">`
       );
@@ -2480,7 +2644,7 @@ export class Wunderbaum {
         part.href = "#";
         part.classList.add("wb-breadcrumb");
         part.dataset.key = n.key;
-        breadcrumb.append(part, this.options.strings!.breadcrumbDelimiter);
+        breadcrumb.append(part, this.options.strings.breadcrumbDelimiter);
       }
     } else {
       breadcrumb.innerHTML = "&nbsp;";
@@ -2604,7 +2768,7 @@ export class Wunderbaum {
     options = Object.assign({ newNodesOnly: false }, options);
     const newNodesOnly = !!options.newNodesOnly;
 
-    const rowHeight = this.options.rowHeightPx!;
+    const rowHeight = this.options.rowHeightPx;
     const vpHeight = this.element.clientHeight;
     const prefetch = RENDER_MAX_PREFETCH;
     // const grace_prefetch = RENDER_MAX_PREFETCH - RENDER_MIN_PREFETCH;
@@ -2684,7 +2848,8 @@ export class Wunderbaum {
 
   /**
    * Call `callback(node)` for all nodes in hierarchical order (depth-first, pre-order).
-   * @see {@link IterableIterator<WunderbaumNode>}, {@link WunderbaumNode.visit}.
+   * @see `wb_node.WunderbaumNode.IterableIterator<WunderbaumNode>`
+   * @see {@link WunderbaumNode.visit}.
    *
    * @param {function} callback the callback function.
    *     Return false to stop iteration, return "skip" to skip this node and
@@ -2856,12 +3021,77 @@ export class Wunderbaum {
    *
    * Previous data is cleared. Note that also column- and type defintions may
    * be passed with the `source` object.
+   * @see {@link Wunderbaum.reload} for a shortcut to reload the last ajax request
+   * and restore the previous state.
    */
-  load(source: SourceType) {
+  async load(source: SourceType) {
     this.clear();
+    this._initialSource = source;
     return this.root.load(source);
   }
 
+  /** Reload the tree and optionally restore state.
+   * Source defaults to last ajax url if any.
+   * Restoring the active node requires stable keys
+   * @see {@link WunderbaumOptions.autoKeys}
+   * @see {@link Wunderbaum.load}
+   * @experimental
+   */
+  async reload(options: ReloadOptions = {}) {
+    const { source = this._initialSource, reactivate = true } = options;
+    if (!source) {
+      this.logWarn("No previous ajax source to reload.");
+      return;
+    }
+    if (!reactivate) {
+      return this.load(source);
+    }
+    const state = this.getState();
+    await this.load(source);
+    return this.setState(state);
+  }
+
+  /**
+   * Make sure that all nodes in the given keyList are accessible.
+   * This may include loading lazy parent nodes.
+   * Recursively load (and optionally expand) all requested node paths.
+   */
+  protected async _loadLazyNodes(
+    keyList: string[],
+    options: LoadLazyNodesOptions = {}
+  ) {
+    const { expand = true } = options;
+    const keySet = new Set<string>(keyList);
+
+    // Make sure that all parent nodes are loaded (and expand if requested)
+    while (keySet.size > 0) {
+      const pendingNodes: Promise<void>[] = [];
+      const curSet = new Set(keySet);
+      for (const key of curSet) {
+        const node = this.findKey(key);
+        if (!node) {
+          continue; // key not yet found (need to load lazy parent?)
+        }
+        keySet.delete(key);
+        if (expand) {
+          pendingNodes.push(node.setExpanded(true));
+        } else if (node.isUnloaded()) {
+          pendingNodes.push(node.loadLazy());
+        }
+        if (node._rowElem) {
+          node._render(); // show spinner even is update is suppressed
+        }
+      }
+      if (pendingNodes.length === 0) {
+        // will not load any more nodes, so if if there are still keys
+        // left in the set, we will never find them
+        this.logWarn(`Could not expand ${keySet.size} nodes:`, keySet);
+        break;
+      }
+      await Promise.allSettled(pendingNodes);
+    }
+  }
+
   /**
    * Disable render requests during operations that would trigger many updates.
    *
@@ -2929,10 +3159,7 @@ export class Wunderbaum {
     filter: string | RegExp | NodeFilterCallback,
     options: FilterNodesOptions
   ): number {
-    return (this.extensions.filter as FilterExtension).filterNodes(
-      filter,
-      options
-    );
+    return this.extensions.filter.filterNodes(filter, options);
   }
 
   /**
@@ -2941,7 +3168,7 @@ export class Wunderbaum {
    * @since 0.9.0
    */
   countMatches(): number {
-    return (this.extensions.filter as FilterExtension).countMatches();
+    return this.extensions.filter.countMatches();
   }
 
   /**
@@ -2952,17 +3179,14 @@ export class Wunderbaum {
     filter: string | NodeFilterCallback,
     options: FilterNodesOptions
   ) {
-    return (this.extensions.filter as FilterExtension).filterBranches(
-      filter,
-      options
-    );
+    return this.extensions.filter.filterBranches(filter, options);
   }
 
   /**
    * Reset the filter.
    */
   clearFilter() {
-    return (this.extensions.filter as FilterExtension).clearFilter();
+    return this.extensions.filter.clearFilter();
   }
   /**
    * Return true if a filter is currently applied.
@@ -2974,6 +3198,6 @@ export class Wunderbaum {
    * Re-apply current filter.
    */
   updateFilter() {
-    return (this.extensions.filter as FilterExtension).updateFilter();
+    return this.extensions.filter.updateFilter();
   }
 }